Menu

Create a verified token

API v3
Last updated March 2021

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": "John Appleseed",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "Worldpay",
      "address2": "1 Milton Road",
      "address3": "The Science Park",
      "postalCode": "CB4 0WE",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "trading name",
    "line2": "order number"
  },
  "merchant": {
    "entity": "default"
  },
  "verificationCurrency": "GBP"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "John Appleseed",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "Worldpay",
      "address2": "1 Milton Road",
      "address3": "The Science Park",
      "postalCode": "CB4 0WE",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "trading name",
    "line2": "order number"
  },
  "merchant": {
    "entity": "default"
  },
  "verificationCurrency": "GBP",
  "namespace": "SHOPPER_ID_1234567890"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/checkout",
    "cardHolderName": "John Appleseed",
    "sessionHref": "https://try.access.worldpay.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9",
    "billingAddress": {
      "address1": "Worldpay",
      "address2": "1 Milton Road",
      "address3": "The Science Park",
      "postalCode": "CB4 0WE",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "merchant": {
    "entity": "default"
  },
  "verificationCurrency": "GBP"
}
{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/checkout",
    "cardHolderName": "John Appleseed",
    "sessionHref": "https://try.access.worldpay.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9",
    "billingAddress": {
      "address1": "Worldpay",
      "address2": "1 Milton Road",
      "address3": "The Science Park",
      "postalCode": "CB4 0WE",
      "city": "Cambridge",
      "state": "Cambridgeshire",
      "countryCode": "GB"
    }
  },
  "merchant": {
    "entity": "default"
  },
  "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 will be 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 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

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