Menu

Create a token

API v3
Last updated March 2023
Change log

Create a card token to secure your customer's 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 card token request

To create a token, POST your request to thetokens:tokensaction 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": "Sherlock Holmes",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "billingAddress": {
            "address1": "221B Baker Street",
            "address2": "Marylebone",
            "address3": "Westminster",
            "postalCode": "NW1 6XE",
            "city": "London",
            "state": "Greater London",
            "countryCode": "GB"
        }
    },
    "merchant": {
        "entity": "MindPalaceLtd"
    }
}
{
    "description": "Test Token Description",
    "paymentInstrument": {
        "type": "card/front",
        "cardHolderName": "Sherlock Holmes",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "billingAddress": {
            "address1": "221B Baker Street",
            "address2": "Marylebone",
            "address3": "Westminster",
            "postalCode": "NW1 6XE",
            "city": "London",
            "state": "Greater London",
            "countryCode": "GB"
        }
    },
    "namespace": "SHOPPER_ID_1234567890",
    "merchant": {
        "entity": "MindPalaceLtd"
    }
}

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, 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.
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.
merchantAn object that contains information about your merchant account.
merchant.entityIdentfies merchant account for billing, reporting and reconciliation. Contact your Implementation Manager for more details.

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

Best Practice: Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

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

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 canupdate the existing tokenusing thetokens:conflictsaction link returned in the response.

Note:

  • The behavior for a conflicting schemeTransactionReference is slightly different from the other fields. If the existing token does not contain a schemeTransactionReference then it is automatically updated to include the one in yourcreate a token request, if a schemeTransactionReference is present. If the token is otherwise the same, you get a 200 OK response. If the token has other conflicted fields you will still get a 409 Conflict response but the schemeTransactionReference is not listed as a conflict.
  • If you are attempting to create a new token with the same card details as an existing token, you would receive a 409 Conflict response in the live environment but a 200 OK response in the test environment. This is because a different schemeTransactionReference is received as part of eachcreate a token request.

Note: Optional fields: If the existing token has a value for the field and yourcreate a token requestdoes not, then this is not counted as a conflict, and no change is made.

The existing token resource reference is returned in the tokenPaymentInstrument object.

Copied!
{
    "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",
        "fundingType": "credit",
        "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
        }]
    }
}

Note: In case of an error, you can get further information in ourerror reference.

Next steps

Update token details

Delete the token