Access Worldpay
/
Verified Tokens cardOnFile Resource

Verified Tokens (v3)

Authentication Header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.

You must use the Authorization header for any request you send to our Token API, unless you are using client certificate authenticating with SSL/TLS.

Accept Header

  Accept: application/vnd.worldpay.verified-tokens-v3.hal+json

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our Account APIs.

DNS Whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

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
cvcstring[ 3 .. 4 ] characters^[0-9]*$
cardHolderNamestring[ 1 .. 255 ] charactersrequired
billingAddressobject
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": "default"
  },
  "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
tokenobjectrequired
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
cvcstring[ 3 .. 4 ] characters^[0-9]*$
cardHolderNamestring[ 1 .. 255 ] charactersrequired
billingAddressobject
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": "default"
  },
  "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
tokenobjectrequired
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": [
          { … }
        ]
      }
    }
  }
}