Menu

Important: We have released a new version. Documentation for our latest version can be foundhere.

Create a token

API v1

Create a token to secure your customer card and billing information, which could help lower yourPCI-DSS compliancecosts.

Note: If you have tokens from a previous provider you canimport the existing tokensto Access Worldpay.

Create a token request

To create a token, POST your request to the tokens:tokens action link returned in yourquery on the tokens root resourceresponse.

When you create a token, you can optionally include the namespace parameter in your request. Click the Create a token with a namespace tab below to see an example request.

Create a token example requests

POST https://try.access.worldpay.com/tokens

Token creation request body:

Copied!
{
    "description": "Test Token Description",
    "paymentInstrument": {
        "type": "card/front",
        "cardHolderName": "John Appleseed",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "billingAddress": {
            "address1": "Worldpay",
            "address2": "1 Milton Road",
            "address3": "The Science Park",
            "postalCode": "CB4 0WE",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        }
    }
}
{
    "description": "Test Token Description",
    "paymentInstrument": {
        "type": "card/front",
        "cardHolderName": "John Appleseed",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "billingAddress": {
            "address1": "Worldpay",
            "address2": "1 Milton Road",
            "address3": "The Science Park",
            "postalCode": "CB4 0WE",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        }
    },
    "namespace": "SHOPPER_ID_1234567890"
}

Description of your create a token request parameters:

ParameterRequiredDescription
descriptionA description of your token. If not supplied, a default description is created for you.
tokenExpiryDateTimeThe date/time after which the token is unavailable, expressed in ISO 8601 format. If not supplied, a default expiry date/time is used.
paymentInstrumentAn object that contains the payment type and details. All sub-fields are mandatory with the exception of billingAddress (see below).
billingAddressAn object containing the billingAddress information. If included, the below fields are mandatory:
  • address1
  • city
  • countryCode
  • postalCode
This is used during payment processing. If the address supplied does not match the address registered with the issuing bank, the payment carries additional risk.
namespaceA namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.
schemeTransactionReferenceA 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 theVerified Tokens APIto create tokens, it is automatically included where applicable.

Responses

Once you've sent your create a token request, one of the following responses is returned:


Next steps

Update token details

Delete the token