Create a verified token

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 the verifiedTokens:cardOnFile action 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"
    }
  },
  "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"
    }
  },
  "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 ISO 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.

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 can be used only once.

Responses

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

If your Verified Token request was successful, the outcome of verification and one of the following response codes is returned:

  • 201 Created
  • 200 OK
  • 409 Conflict

For more information about these response codes, seeCreate a token responses.

The response contains the embedded results of the:

Copied!
{
  "_embedded": {
    "verification": {
      "outcome": "verified",
      "schemeTransactionReference": "000000000000020005060720116005060",
      "checkedAt": "2020-08-18T14:29:10.641180Z",
      "riskFactors": [
        {
          "risk": "matched",
          "type": "cvc"
        },
        {
          "risk": "matched",
          "detail": "postcode",
          "type": "avs"
        },
        {
          "risk": "matched",
          "detail": "address",
          "type": "avs"
        }
      ],
      "paymentInstrument": {
        "type": "card/plain",
        "card": {
          "expiryDate": {
            "month": 5,
            "year": 2035
          },
          "brand": "visa",
          "fundingType": "debit",
          "paymentAccountReference": "reference"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "name": "verifications",
            "templated": true
          }
        ]
      }
    },
    "token": {
      "tokenId": "9902480679618049603",
      "description": "Test Token Description",
      "tokenExpiryDateTime": "2021-08-18T14:30:40Z",
      "schemeTransactionReference": "000000000000020005060720116005060",
      "tokenPaymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
      },
      "paymentInstrument": {
        "type": "card/masked",
        "cardNumber": "4444********1111",
        "cardHolderName": "Testy McTester",
        "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"
        },
        "bin": "444433",
        "brand": "VISA"
      },
      "_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
          }
        ]
      }
    }
  }
}

Note: The above is a response for a successful verified token creation. Please see theTokens APIandVerifications APIfor more information on the respective embedded response data.

You canquery your verificationto get your next available actions links.

GET https://try.access.worldpay.com/verifications/accounts/{resource}

If the verification failed, a 206 Partial Content HTTP response status code is returned. The response body contains a link to theverificationresult as a token is not created.

Copied!
{
  "_embedded": {
    "verification": {
      "outcome": "not verified",
      "checkedAt": "2020-08-18T14:29:10.641180Z",
      "riskFactors": [
        {
          "risk": "not_matched",
          "type": "cvc"
        },
        {
          "risk": "matched",
          "type": "avs",
          "detail": "postcode"
        },
        {
          "risk": "not_matched",
          "type": "avs",
          "detail": "address"
        }
      ],
      "paymentInstrument": {
        "type": "card/plain",
        "card": {
          "brand": "visa",
          "fundingType": "debit"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "name": "verifications",
            "templated": true
          }
        ]
      }
    }
  }
}


Next steps


Query the verification and token
Take a payment
Take your first and subsequent recurring payment
Take your first and subsequent card on file payment