A collection of tokens representing payment instruments.
Download OpenAPI specification:Download
A collection of tokens representing payment instruments.
testing (try)
live
Creating a new token for the payment instrument.
description | string [ 1 .. 255 ] characters ^[^&<]*$ A description of your token. If not supplied, a default description is created for you. |
tokenExpiryDateTime | string <date-time> The date/time after which the token is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 7 days in Try and 4 years in the Live environment. |
namespace | string [ 1 .. 64 ] characters A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace. |
schemeTransactionReference | string [ 1 .. 56 ] characters ^[a-zA-Z0-9 ]*$ A value provided by Visa or Mastercard which tracks recurring transactions. |
required | object An object that contains the payment type and details. All sub-fields are mandatory with the exception of billingAddress (see below). |
merchant required | object An object that contains information about your merchant account. |
Creating a token from payment instrument
{ "paymentInstrument": { "type": "card/front", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 1, "year": 2025 }, "cardHolderName": "Testy McTester" }, "merchant": { "entity": "default" } }
200
A token already exists matching the details in the request.
required | object |
description required | string [ 1 .. 255 ] characters ^[^&<]*$ A description of your token. If not supplied, a default description is created for you. |
tokenExpiryDateTime required | string <date-time> The date/time after which the token is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 7 days in Try and 4 years in the Live environment. |
required | object |
tokenId | string [ 15 .. 21 ] characters ^[0-9A-HJ-NP-Z]+$ |
namespace | string [ 1 .. 64 ] characters |
schemeTransactionReference | string [ 1 .. 56 ] characters ^[a-zA-Z0-9 ]*$ A value provided by Visa or Mastercard which tracks recurring transactions. |
201
A new token was created.
409
A token already exists conflicting with some details in the request.
A 200 OK response means that you've already tokenized the card and that all data supplied in your create a token request matches the data stored with Access Worldpay.
Sometimes, a token can be matched even if the data isn't quite the same. For example, if Access Worldpay has a billingAddress on file, the existing billingAddress is retained if no billingAddress was supplied in your request. Additionally, you receive the 200 OK response code.
The existing token resource reference is returned in the tokenPaymentInstrument object.
{ "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T09:19:35Z", "paymentInstrument": { "type": "card/masked", "cardNumber": "4444********1111", "cardHolderName": "Sherlock Holmes", "cardExpiryDate": { "month": 5, "year": 2035 }, "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" }, "bin": "444433", "brand": "VISA" }, "_links": { "tokens:token": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokens:description": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9" }, "tokens:billingAddress": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9" }, "curies": [ { "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true } ] } }
A token representing a payment instrument.
200
The detail for this token.
required | object |
description required | string [ 1 .. 255 ] characters ^[^&<]*$ A description of your token. If not supplied, a default description is created for you. |
tokenExpiryDateTime required | string <date-time> The date/time after which the token is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 7 days in Try and 4 years in the Live environment. |
required | object |
tokenId | string [ 15 .. 21 ] characters ^[0-9A-HJ-NP-Z]+$ |
namespace | string [ 1 .. 64 ] characters |
schemeTransactionReference | string [ 1 .. 56 ] characters ^[a-zA-Z0-9 ]*$ A value provided by Visa or Mastercard which tracks recurring transactions. |
Retrieve details about a token.
{ "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ" }, "tokenId": "9925760692793807595", "description": "Token Description", "tokenExpiryDateTime": "2025-01-23T10:57:01Z", "paymentInstrument": { "type": "card/masked", "cardNumber": "4444********1111", "cardHolderName": "Card Holder Name", "cardExpiryDate": { "month": 5, "year": 2035 }, "bin": "444433", "brand": "VISA", "billingAddress": { "address1": "Address 1", "address2": "Address 2", "address3": "Address 3", "postalCode": "Postal Code", "city": "City", "state": "State", "countryCode": "XX" } }, "_links": { "tokens:token": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ" }, "tokens:description": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXdW9oYzR3RUFEM2FCQnlaejhsZ1poTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXT0pLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXT0pLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9" }, "tokens:billingAddress": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXTlpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXTThZcVl5OWJFUHNnbzNpTHd1NlpJSTJxUUNRVXZybWJpRkdyQ0NNQ0g0ZlpsNlBnc1NkL0h5VkRCKyt0Ym9wMGs9In0" }, "tokens:networkToken": { "href": "https://try.access.worldpay.com/tokens/network" }, "curies": [ { "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true } ] } }
Updating different fields represented by the token
schemeTransactionReference | string [ 1 .. 56 ] characters ^[a-zA-Z0-9 ]*$ A value provided by Visa or Mastercard which tracks recurring transactions. |
cardHolderName | string [ 1 .. 255 ] characters The name on the customer's card. |
description | string [ 1 .. 255 ] characters ^[^&<]*$ A description of your token. If not supplied, a default description is created for you. |
month | integer [ 1 .. 12 ] |
year | integer <= 9999 |
address1 | string |
address2 | string |
address3 | string |
postalCode | string |
city | string |
state | string |
countryCode | string = 2 characters ^[A-Z]*$ |
Update a billing address.
"{ \"address1\": \"1 Test Street\", \"address2\": \"Address line 2\", \"address3\": \"Address line 3\", \"postalCode\": \"TE12 34ST\", \"city\": \"Testville\", \"state\": \"Testshire\", \"countryCode\": \"TS\" }"
204
The token was successfully updated.