Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.
Access Worldpay
/
Verified Tokens cardOnFile Resource

Verified Tokens (v3)

Verified Tokens ensures that your customer's payment details are valid and CIT compliant when creating a token.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
testing (try)
https://try.access.worldpay.com/
live
https://access.worldpay.com/

Verified Tokens cardOnFile Resource

Request

Create a verified cardOnFile token by sending a request to cardOnFile resource. A cardOnFile verified token allows you to take payments that are made by the customer using a stored verified token, such as in one-click or in-app purchases.

Bodyapplication/vnd.worldpay.verified-tokens-v3.hal+json
paymentInstrumentanyrequired

An object that contains the card details or token location.

typestringrequired
Example:

"card/plain"

Discriminator
cardNumberstring[ 10 .. 19 ] characters^[0-9]*$required
cardExpiryDateobjectrequired
monthinteger[ 1 .. 12 ]required
yearinteger<= 9999required
cvcstring[ 3 .. 4 ] characters^[0-9]*$
cardHolderNamestring[ 1 .. 255 ] charactersrequired
billingAddressobject
address1stringrequired
address2string
address3string
postalCodestringrequired
citystringrequired
statestring
countryCodestring= 2 characters^[A-Z]*$required
merchantobjectrequired
entitystringrequired
verificationCurrencystring= 3 characters^[A-Z]*$required
descriptionstring[ 1 .. 255 ] characters^[^&<]*$
tokenExpiryDateTimestring(date-time)
namespacestring[ 1 .. 64 ] characters
narrativeobject
line1string[ 1 .. 24 ] charactersrequired
line2string[ 1 .. 24 ] characters
application/vnd.worldpay.verified-tokens-v3.hal+json

Creating a new token for cardOnFile transactions when supplying all the payment instrument details.

{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "SherlockHolmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "221BBakerStreet",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW16XE",
      "city": "London",
      "state": "GreaterLondon",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "TheMindPalaceLtd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP",
  "namespace": "SHOPPER_ID_1234567890"
}

Responses

The payload has been verified and a matching Token already exists. This does not include token meta data, which still may be different

Bodyapplication/vnd.worldpay.verified-tokens-v3.hal+json
_embeddedobjectrequired
verificationobjectrequired
outcomestringrequired
Example:

"verified"

schemeTransactionReferencestring
Example:

"000000000000020005060720116005060"

checkedAtstring(date-time)required
Example:

"2024-01-26T17:11:46.226297Z"

riskFactorsArray of objects
paymentInstrumentobject
_linksobjectrequired
tokenobjectrequired
tokenIdstring[ 15 .. 21 ] characters^[0-9A-HJ-NP-Z]+$
Example:

"9902480679618049603"

descriptionstring[ 1 .. 255 ] characters^[^&<]*$required
Example:

"Test Token Description"

namespacestring[ 1 .. 64 ] characters
tokenExpiryDateTimestring(date-time)required
Example:

"2021-08-18T14:30:40Z"

schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$
Example:

"000000000000020005060720116005060"

tokenPaymentInstrumentobjectrequired
paymentInstrumentobjectrequired
_linksobjectrequired
Response
application/vnd.worldpay.verified-tokens-v3.hal+json

Matching an existing token for cardOnFile transactions when supplying all the payment instrument details.

{
  "_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": {
          "number": { … },
          "issuer": { … },
          "expiryDate": { … },
          "brand": "visa",
          "fundingType": "debit",
          "paymentAccountReference": "reference"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "payments:cardOnFileAuthorize": {
          "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "payments:recurringAuthorize": {
          "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "payments:recurringSale": {
          "href": "https://try.access.worldpay.com/payments/sales/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "curies": [
          { … }
        ]
      }
    },
    "token": {
      "tokenId": "9902480679618049603",
      "description": "TestTokenDescription",
      "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": "SherlockHolmes",
        "cardExpiryDate": {
          "month": 5,
          "year": 2035
        },
        "billingAddress": {
          "address1": "221BBakerStreet",
          "address2": "Marylebone",
          "address3": "Westminster",
          "postalCode": "NW16XE",
          "city": "London",
          "state": "GreaterLondon",
          "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": [
          { … }
        ]
      }
    }
  }
}

Verified Tokens oneTime Resource

Request

Create a verified oneTime token by sending a request to oneTime resource. A oneTime verified token allows you to take payments that are made by the customer using a stored verified token, such as in one-click or in-app purchases.

Bodyapplication/vnd.worldpay.verified-tokens-v3.hal+json
paymentInstrumentanyrequired

An object that contains the card details or token location.

typestringrequired
Example:

"card/plain"

Discriminator
cardNumberstring[ 10 .. 19 ] characters^[0-9]*$required
cardExpiryDateobjectrequired
monthinteger[ 1 .. 12 ]required
yearinteger<= 9999required
cvcstring[ 3 .. 4 ] characters^[0-9]*$
cardHolderNamestring[ 1 .. 255 ] charactersrequired
billingAddressobject
address1stringrequired
address2string
address3string
postalCodestringrequired
citystringrequired
statestring
countryCodestring= 2 characters^[A-Z]*$required
merchantobjectrequired
entitystringrequired
verificationCurrencystring= 3 characters^[A-Z]*$required
descriptionstring[ 1 .. 255 ] characters^[^&<]*$
tokenExpiryDateTimestring(date-time)
namespacestring[ 1 .. 64 ] characters
narrativeobject
line1string[ 1 .. 24 ] charactersrequired
line2string[ 1 .. 24 ] characters
application/vnd.worldpay.verified-tokens-v3.hal+json

Creating a new token for oneTime transactions when supplying all the payment instrument details.

{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "SherlockHolmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "221BBakerStreet",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW16XE",
      "city": "London",
      "state": "GreaterLondon",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "TheMindPalaceLtd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "verificationCurrency": "GBP",
  "namespace": "SHOPPER_ID_1234567890"
}

Responses

The payload has been verified and a matching Token already exists. This does not include token meta data, which still may be different

Bodyapplication/vnd.worldpay.verified-tokens-v3.hal+json
_embeddedobjectrequired
verificationobjectrequired
outcomestringrequired
Example:

"verified"

checkedAtstring(date-time)required
Example:

"2024-01-26T17:11:46.226297Z"

riskFactorsArray of objects
paymentInstrumentobject
_linksobjectrequired
tokenobjectrequired
tokenIdstring[ 15 .. 21 ] characters^[0-9A-HJ-NP-Z]+$
Example:

"9902480679618049603"

descriptionstring[ 1 .. 255 ] characters^[^&<]*$required
Example:

"Test Token Description"

namespacestring[ 1 .. 64 ] characters
tokenExpiryDateTimestring(date-time)required
Example:

"2021-08-18T14:30:40Z"

schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$
Example:

"000000000000020005060720116005060"

tokenPaymentInstrumentobjectrequired
paymentInstrumentobjectrequired
_linksobjectrequired
Response
application/vnd.worldpay.verified-tokens-v3.hal+json

Matching an existing token for oneTime transactions when supplying all the payment instrument details.

{
  "_embedded": {
    "verification": {
      "outcome": "verified",
      "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": {
          "number": { … },
          "issuer": { … },
          "expiryDate": { … },
          "brand": "visa",
          "fundingType": "debit",
          "paymentAccountReference": "reference"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [
          { … }
        ]
      }
    },
    "token": {
      "tokenId": "9902480679618049603",
      "description": "TestTokenDescription",
      "tokenExpiryDateTime": "2021-08-18T14:30:40Z",
      "tokenPaymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
      },
      "paymentInstrument": {
        "type": "card/masked",
        "cardNumber": "4444********1111",
        "cardHolderName": "SherlockHolmes",
        "cardExpiryDate": {
          "month": 5,
          "year": 2035
        },
        "billingAddress": {
          "address1": "221BBakerStreet",
          "address2": "Marylebone",
          "address3": "Westminster",
          "postalCode": "NW16XE",
          "city": "London",
          "state": "GreaterLondon",
          "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": [
          { … }
        ]
      }
    }
  }
}