Menu

Create a verified token

API v3
Last updated January 2023
Change log

Use our Verified Tokens API to orchestrate verifying your customer's payment details and creating a token, in a single request.

Create a verified token request

To create a verified token, POST your request to theverifiedTokens:cardOnFileaction link returned in the response of yourverifiedTokens root resourcerequest.

When you create a verified token request, you can optionally include the namespace parameter. Choose either of the Card with a namespace or Session with a namespace tabs below to see an example.

Note: Seecreate a tokenfor more information about namespaces.

POST https://try.access.worldpay.com/verifiedTokens/cardOnFile

Verified token creation request body:

Copied!
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "Sherlock Holmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "221B Baker Street",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW1 6XE",
      "city": "London",
      "state": "Greater London",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "The Mind Palace Ltd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "Sherlock Holmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "221B Baker Street",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW1 6XE",
      "city": "London",
      "state": "Greater London",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "The Mind Palace Ltd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP",
  "namespace": "SHOPPER_ID_1234567890"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/checkout",
    "cardHolderName": "Sherlock Holmes",
    "sessionHref": "https://try.access.worldpay.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9",
    "billingAddress": {
      "address1": "221B Baker Street",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW1 6XE",
      "city": "London",
      "state": "Greater London",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "The Mind Palace Ltd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/checkout",
    "cardHolderName": "Sherlock Holmes",
    "sessionHref": "https://try.access.worldpay.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9",
    "billingAddress": {
      "address1": "221B Baker Street",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW1 6XE",
      "city": "London",
      "state": "Greater London",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "The Mind Palace Ltd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP",
  "namespace": "SHOPPER_ID_1234567890"
}

Description of your 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 cvc and billingAddress (see below).
cvcThe CVC number from the card. This is used during the verification process and if not supplied, the verification acceptance rate is likely to be lower.
billingAddressAn object containing the billing address information. If included, the below fields are mandatory:
  • address1
  • city
  • countryCode
  • postalCode
This is used during the verification and payment processes. If the address supplied does not match the address registered with the issuing bank, the payment carries additional risk.
merchantAn object that contains information about the merchant. Contact yourImplementation Managerfor more information.
verificationCurrencyThe 3 character currency code. See our list ofsupported currencies.
namespaceA namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.
narrativeThe narrative object helps your customers to better identify you on their statement. If included, you must provide subfield line1, which is used to provide basic details about the merchant. Optionally, you can also include subfield line2, which can be used for additional context about the payment or merchant. SeeFormattingsection for more information.

Using a session

If you are using theAccess Checkout SDK, the paymentInstrument.type changes from card/plain to card/checkout, and sessionHref is used instead of cardNumber, cardExpiryDate and cvc.

The sessionHref looks like this :

Copied!
https://try.access.worldpay.com/verifiedTokens/session/eyJrIjoxLCJkIjoicGtubGtlWDJzeTVTdG1Qa3F5WlZ0emdJY1JEbjIyZVJ6KzlOR245YWlOMFVsVytCYitTa1NWa3l0RU1DQjZXYiJ9

Note: The session has a lifespan of one minute and you can only use this once.

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 request, one of the following responses is returned:

Note: In case of any errors, you can get further information in ourerror reference.


Next steps

Query the verification and token
Take a payment