openapi: 3.0.1 info: title: Tokens description: A collection of tokens representing payment instruments. version: '3' servers: - url: https://try.access.worldpay.com description: testing (try) - url: https://access.worldpay.com description: live paths: /tokens: post: tags: - Token summary: Create a new token description: Creating a new token for the payment instrument. operationId: createSecurityToken requestBody: content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/token_creation' examples: Creating a Token: description: Creating a token from payment instrument value: paymentInstrument: type: card/front cardNumber: '4444333322221111' cardExpiryDate: month: 1 year: 2025 cardHolderName: Testy McTester merchant: entity: default responses: '200': headers: Accept: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Content-Type: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Location: schema: type: string format: uri description: A URI identifying the created token resource. description: A token already exists matching the details in the request. content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/tokens_token_200_response' examples: Creating a token: description: >- 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. value: 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 '201': headers: Accept: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Content-Type: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Location: schema: type: string format: uri description: A URI identifying the created token resource. description: A new token was created. content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/tokens_token_201_response' examples: Token Created: description: >- If this is the first time you've tokenized the card, a 201 Created response is returned.

Your response contains a tokenPaymentInstrument object which contains the href to the token resource. The response also includes next available action links, e.g. updating and deleting the token. value: 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 credit: null countryCode: GB _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 '409': headers: Accept: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Content-Type: schema: type: string description: application/vnd.worldpay.tokens-v2.hal+json Location: schema: type: string format: uri description: A URI identifying the conflicting token resource. description: A token already exists conflicting with some details in the request. content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/tokens_token_409_response' examples: Conflict: description: >- A 409 Conflict response means that you've already tokenized the card, but some of the data supplied in your create a token request is different from the data in the existing token.

This conflict could be caused by a differentiation in the cardHolderName, card expiry month, card expiry year billingAddress or schemeTransactionReference (see note below) fields.

In this case, the data that we have on file is retained. The data which caused the conflict is returned in a conflicts object. If you would like to resolve the conflict, you can update the existing token using the tokens:conflicts action link returned in the response. value: 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 conflicts: paymentInstrument: cardHolderName: Sherlock Holmes conflictsExpiryDateTime: '2019-06-24T09:49:35Z' _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 tokens:conflicts: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0ODUrN2hvZ0cyK1JvQ3JKdUtFZnU5UTFsdTdwODVHTUcwYy92VW02MDlJd2pHQllvcW0zanhWQ3p3Zk9OUW9CYUZtQ1hNbFhwM3lhSXlkYVlNYWJnQUdQUHFpRVAxVXVpZHM2Y2tvTjEvOGNJdFQ0WkVlVEJIVWF6T1dlWTlQMkpnPT0ifQ curies: - href: >- https://try.access.worldpay.com/rels/tokens/{rel}.json name: tokens templated: true /tokens/{tokenId}: get: tags: - Token summary: Retrieve the detail for this token description: A token representing a payment instrument. operationId: getSecurityToken parameters: - name: tokenId in: path description: Access Worldpay encrypted token. required: true schema: type: string responses: '200': description: The detail for this token. content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/tokens_token_200_response' examples: Retrieve details about a token.: description: Retrieve details about a token. value: 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 Retrieve details about a token with a network payment instrument.: description: >- Retrieve details about a token with a network payment instrument. value: 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/network+masked cardNumber: 4818********6530 last4Digits: '6530' networkType: APPLEPAY cardExpiryDate: month: 5 year: 2035 bin: '444433' brand: VISA _links: tokens:token: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ curies: - href: >- https://try.access.worldpay.com/rels/tokens/{rel}.json name: tokens templated: true Retrieve details about a token with a namespace.: description: Retrieve details about a token with a namespace. value: tokenPaymentInstrument: type: card/tokenized href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abnZtYjM3RXppMy84N2J6ZWlXYkhyUiJ9 tokenId: '9925760692793807595' description: Token Description tokenExpiryDateTime: '2025-01-23T10:57:01Z' namespace: my-authenticated-shopper 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/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abnZtYjM3RXppMy84N2J6ZWlXYkhyUiJ9 tokens:description: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abXlBdGFNaFRIdE1Oc2lybUZQeWFWOTFMR3BqVW1LaDBPdUsrYkczWEdWWWc9PSJ9 tokens:cardHolderName: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abGFqUW1IQ2k5NWk0SEx3U0JrYWdHSWlTdTNNRkZ2V0NPN09FekprQW15cjlZRk1ySXhqaU1GV1EybnhhMFlpOE09In0 tokens:cardExpiryDate: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abGFqUW1IQ2k5NWk0SEx3U0JrYWdHSWlTdTNNRkZ2V0NPN09FekprQW15cnhJbEp4ZXFaWHZERExEMk9CYU5iRE09In0 tokens:billingAddress: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abGFqUW1IQ2k5NWk0SEx3U0JrYWdHSVdVYnFxcG4zdVdMalNSblJLSHJNTmZRVWlIN2ZxaU9kazlrYnNueU50Tjg9In0 tokens:schemeTransactionReference: href: >- https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXaGdPVU5iVmZ0Rm5TUDZuK3N1Mm5abGFqUW1IQ2k5NWk0SEx3U0JrYWdHSVBHS21Ndld4RDdJS040aThMdW1TQ05xa0FrRkw2NW00aFJxd2dqQWgrSDJaZWo0TEVuZng4bFF3ZnZyVzZLZEoifQ 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 put: tags: - Token summary: Update this token. description: Updating different fields represented by the token operationId: updateSecurityToken parameters: - name: tokenId in: path description: Access Worldpay encrypted token. required: true schema: type: string requestBody: content: application/vnd.worldpay.tokens-v2.hal+json: schema: $ref: '#/components/schemas/tokens_token' examples: Update a billing address.: description: Update a billing address. value: >- { "address1": "1 Test Street", "address2": "Address line 2", "address3": "Address line 3", "postalCode": "TE12 34ST", "city": "Testville", "state": "Testshire", "countryCode": "TS" } Update a card expiry date.: description: Update a card expiry date. value: '{ "month": 1, "year": 2050 }' Update a card holder name.: description: Update a card holder name. value: '"new name"' Update a token description.: description: Update a token description. value: '"new description"' Update a scheme transaction reference for a token.: description: Update a scheme transaction reference for a token. value: '"000000000000020005060720116005060"' responses: '204': description: The token was successfully updated. delete: tags: - Token summary: Delete this token. description: Deleting a token based on an encrypted tokenId operationId: deleteSecurityToken parameters: - name: tokenId in: path description: Access Worldpay encrypted token. required: true schema: type: string responses: '204': description: The token was successfully deleted. components: schemas: tokens_token_200_response: required: - tokenPaymentInstrument - description - tokenExpiryDateTime - paymentInstrument - _links type: object properties: tokenPaymentInstrument: type: object properties: type: type: string href: type: string description: maxLength: 255 minLength: 1 pattern: ^[^&<]*$ type: string description: >- A description of your token. If not supplied, a default description is created for you. tokenExpiryDateTime: type: string format: date-time description: >- 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.

We extend the expiry by 7 days or 4 years after any use of the token, if under half of the time remains on the token. paymentInstrument: required: - cardNumber - cardExpiryDate type: object properties: cardNumber: maxLength: 19 minLength: 10 pattern: ^[0-9\*]*$ type: string description: Contains your customer's card number. cardExpiryDate: required: - month - year type: object properties: month: maximum: 12 minimum: 1 type: integer year: maximum: 9999 type: integer cardHolderName: maxLength: 255 minLength: 1 type: string description: The name on the customer's card. bin: maxLength: 6 minLength: 6 pattern: \d{6} type: string brand: maxLength: 255 minLength: 1 type: string billingAddress: required: - address1 - postalCode - city - countryCode type: object description: Contains the billing address information. properties: address1: type: string postalCode: type: string city: type: string countryCode: maxLength: 2 minLength: 2 pattern: ^[A-Z]*$ type: string address2: type: string address3: type: string state: type: string networkType: maxLength: 255 minLength: 1 type: string last4Digits: maxLength: 4 minLength: 4 type: string tokenId: maxLength: 21 minLength: 15 pattern: ^[0-9A-HJ-NP-Z]+$ type: string namespace: maxLength: 64 minLength: 1 type: string schemeTransactionReference: maxLength: 56 minLength: 1 pattern: ^[a-zA-Z0-9 ]*$ type: string description: >- A value provided by Visa or Mastercard which tracks recurring transactions.

Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/access/verified-tokens/@v3/get-started.md) to create tokens, it is automatically included where applicable. tokens_token_201_response: required: - tokenPaymentInstrument - description - tokenExpiryDateTime - paymentInstrument - _links type: object properties: tokenPaymentInstrument: type: object properties: type: type: string description: Indicating the type of this token. href: type: string description: Link to the corresponding token. description: maxLength: 255 minLength: 1 pattern: ^[^&<]*$ type: string description: >- A description of your token. If not supplied, a default description is created for you. tokenExpiryDateTime: type: string format: date-time description: >- 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.

We extend the expiry by 7 days or 4 years after any use of the token, if under half of the time remains on the token. paymentInstrument: required: - cardNumber - cardExpiryDate type: object properties: cardNumber: maxLength: 19 minLength: 10 pattern: ^[0-9\*]*$ type: string cardExpiryDate: required: - month - year type: object properties: month: maximum: 12 minimum: 1 type: integer year: maximum: 9999 type: integer type: type: string cardHolderName: maxLength: 255 minLength: 1 type: string description: The name on the customer's card. bin: maxLength: 6 minLength: 6 pattern: \d{6} type: string brand: maxLength: 255 minLength: 1 type: string billingAddress: required: - address1 - postalCode - city - countryCode type: object properties: address1: type: string postalCode: type: string city: type: string countryCode: maxLength: 2 minLength: 2 pattern: ^[A-Z]*$ type: string address2: type: string address3: type: string state: type: string networkType: maxLength: 255 minLength: 1 type: string last4Digits: maxLength: 4 minLength: 4 type: string tokenId: maxLength: 21 minLength: 15 pattern: ^[0-9A-HJ-NP-Z]+$ description: >- Worldpay's internal identifier for a token. If supplied, must be between 15 and 21 characters, must consist of digits and upper-case characters excluding 'I' and 'O'. type: string namespace: maxLength: 64 minLength: 1 type: string description: >- The reference by which a client can identify a shopper. If supplied, must be between 1 and 64 characters, must not start with an underscore, must not contain spaces, '&' or '<'. schemeTransactionReference: maxLength: 56 minLength: 1 pattern: ^[a-zA-Z0-9 ]*$ type: string description: >- A value provided by Visa or Mastercard which tracks recurring transactions.

Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/access/verified-tokens/@v3/get-started.md) to create tokens, it is automatically included where applicable. tokens_token_409_response: required: - tokenPaymentInstrument - description - tokenExpiryDateTime - paymentInstrument - _links type: object properties: tokenPaymentInstrument: type: object properties: type: type: string description: Indicating the type of this token. href: type: string description: Link to the corresponding token. description: maxLength: 255 minLength: 1 pattern: ^[^&<]*$ type: string description: >- A description of your token. If not supplied, a default description is created for you. tokenExpiryDateTime: type: string format: date-time description: >- 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.

We extend the expiry by 7 days or 4 years after any use of the token, if under half of the time remains on the token. paymentInstrument: required: - cardNumber - cardExpiryDate type: object properties: cardNumber: maxLength: 19 minLength: 10 pattern: ^[0-9\*]*$ type: string cardExpiryDate: required: - month - year type: object properties: month: maximum: 12 minimum: 1 type: integer year: maximum: 9999 type: integer type: type: string cardHolderName: maxLength: 255 minLength: 1 type: string description: The name on the customer's card. bin: maxLength: 6 minLength: 6 pattern: \d{6} type: string brand: maxLength: 255 minLength: 1 type: string billingAddress: required: - address1 - postalCode - city - countryCode type: object properties: address1: type: string postalCode: type: string city: type: string countryCode: maxLength: 2 minLength: 2 pattern: ^[A-Z]*$ type: string address2: type: string address3: type: string state: type: string networkType: maxLength: 255 minLength: 1 type: string last4Digits: maxLength: 4 minLength: 4 type: string tokenId: type: string maxLength: 21 minLength: 15 pattern: ^[0-9A-HJ-NP-Z]+$ description: >- Worldpay's internal identifier for a token. If supplied, must be between 15 and 21 characters, must consist of digits and upper-case characters excluding 'I' and 'O'. namespace: maxLength: 64 minLength: 1 type: string description: >- The reference by which a client can identify a shopper. If supplied, must be between 1 and 64 characters, must not start with an underscore, must not contain spaces, '&' or '<'. schemeTransactionReference: maxLength: 56 minLength: 1 pattern: ^[a-zA-Z0-9 ]*$ type: string description: >- A value provided by Visa or Mastercard which tracks recurring transactions.

Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/access/verified-tokens/@v3/get-started.md) to create tokens, it is automatically included where applicable. token_creation: type: object properties: description: type: string minLength: 1 maxLength: 255 pattern: ^[^&<]*$ description: >- A description of your token. If not supplied, a default description is created for you. tokenExpiryDateTime: type: string format: date-time description: >- 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.

We extend the expiry by 7 days or 4 years after any use of the token, if under half of the time remains on the token. namespace: type: string minLength: 1 maxLength: 64 description: >- 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: maxLength: 56 minLength: 1 pattern: ^[a-zA-Z0-9 ]*$ description: >- A value provided by Visa or Mastercard which tracks recurring transactions.

Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/access/verified-tokens/@v3/get-started.md) to create tokens, it is automatically included where applicable. type: string paymentInstrument: type: object description: >- An object that contains the payment type and details. All sub-fields are mandatory with the exception of billingAddress (see below). properties: type: type: string description: card/front cardHolderName: type: string maxLength: 255 minLength: 1 description: The name on the customer's card. cardExpiryDate: required: - month - year type: object properties: month: type: integer maximum: 12 minimum: 1 year: type: integer maximum: 9999 minimum: 1 cardNumber: type: string maxLength: 19 minLength: 10 pattern: ^[0-9]*$ description: Contains your customer's card number. billingAddress: required: - address1 - postalCode - city - countryCode type: object description: Contains the billing address information. properties: address1: type: string maxLength: 80 minLength: 1 postalCode: type: string maxLength: 15 minLength: 1 city: type: string maxLength: 50 minLength: 1 countryCode: maxLength: 2 minLength: 2 pattern: ^[A-Z]*$ type: string address2: maxLength: 80 type: string address3: maxLength: 80 type: string state: type: string maxLength: 30 minLength: 1 merchant: type: object description: An object that contains information about your merchant account. required: - paymentInstrument - merchant tokens_token: type: object properties: schemeTransactionReference: maxLength: 56 minLength: 1 pattern: ^[a-zA-Z0-9 ]*$ type: string description: >- A value provided by Visa or Mastercard which tracks recurring transactions.

Note: You are not normally expected to provide a value for schemeTransactionReference. If you are using the [Verified Tokens API](/products/access/verified-tokens/@v3/get-started.md) to create tokens, it is automatically included where applicable. cardHolderName: maxLength: 255 minLength: 1 type: string description: The name on the customer's card. description: maxLength: 255 minLength: 1 pattern: ^[^&<]*$ type: string description: >- A description of your token. If not supplied, a default description is created for you. month: type: integer maximum: 12 minimum: 1 year: maximum: 9999 type: integer address1: type: string address2: type: string address3: type: string postalCode: type: string city: type: string state: type: string countryCode: maxLength: 2 minLength: 2 pattern: ^[A-Z]*$ type: string securitySchemes: BasicAuth: type: http scheme: basic security: - BasicAuth: [] tags: - name: Token description: A token representing a payment instrument.