openapi: 3.0.1
info:
title: Tokens
description: A collection of tokens representing payment instruments.
version: '1'
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-v1.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-v1.hal+json
Content-Type:
schema:
type: string
description: application/vnd.worldpay.tokens-v1.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-v1.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
_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-v1.hal+json
Content-Type:
schema:
type: string
description: application/vnd.worldpay.tokens-v1.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-v1.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
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-v1.hal+json
Content-Type:
schema:
type: string
description: application/vnd.worldpay.tokens-v1.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-v1.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
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-v1.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
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 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
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-v1.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.
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.
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.
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.