For tokenization several API endpoints are available. For a general description of tokenization and dataflows, see the Tokenization Guide .
Register a Token
The Register token endpoint registers a new token in the payment wallet of a shopper for a particular merchant.
The shopper is required to complete the token registration by performing a payment, once the token has been created. Therefore, use List Payment Methods to determine the available payment methods for tokenization and use Start Payment to complete the token registration.
POST /ps/api/public/v1/merchants/{merchant_key}/shoppers/{shopper_key}/tokens
Identifiers
| Name | Type | Description |
|---|---|---|
| merchant_key | MerchantKey | The key of the merchant. |
| shopper_key | ShopperKey | The shopper key as returned by the create-shopper endpoint. |
Parameters
Not applicable.
Request Data
| Field | Type | M | Description |
|---|---|---|---|
| order_key | OrderKey | O | The order key used to generate the token. If not given, then an implicit order is generated. |
| authentication_methods | AuthenticationMethod[] | M | The used authentication methods that successfully authenticated the shopper at the webshop. |
Response Data
| Field | Type | M | Description |
|---|---|---|---|
| id | PaymentIdentifier | M | The payment identifier. |
| order_key | OrderKey | M | The order key, the same as in the request if given, else the key of the generated order. |
| token_key | UUID | M | The token key under which the payment details are registered. |
HTTP Status
| Status | Meaning |
|---|---|
| 201 (Created) | The token is successfully created. |
| 400 (Bad Request) | The request was not valid. |
| 401 (Not Authorized) | The merchant is not authorized to execute the request. |
| 403 (Forbidden) | The merchant is not found. |
Examples
Below are two examples, one for token registration with an implicit order and the other with an explicit order.
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens \
-d '{
"authentication_methods": ["USER_PASSWORD","OUT_OF_BAND"]
}'
< Http 201 Created
< '{
"order_key" : "3B88E0EF13E37D6A56AE949AD9E56961",
"token_key" : "252327a1-711b-421a-bf36-4dd34243fde9"
}'
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens \
-d '{
"order_key" : "3B88E0EF13E37D6A56AE949AD9E56961",
"authentication_methods": ["USER_PASSWORD","OUT_OF_BAND"]
}'
< Http 201 Created
< '{
"order_key" : "3B88E0EF13E37D6A56AE949AD9E56961",
"token_key" : "252327a1-711b-421a-bf36-4dd34243fde9"
}'
Get Tokens and Token Details
The get tokens endpoint returns the tokens for a given merchant key and a given shopper key.
This endpoint also allows the retrieval of details of a particular token, by specifying a specific token.
For ideal, user preferences will be present for a valid token under "additional_ideal_token_details".
GET /ps/api/public/v1/merchants/{merchant_key}/shoppers/{shopper_key}/tokens/{token_key}
GET /ps/api/public/v1/merchants/{merchant_key}/shoppers/{shopper_key}/tokens?page=1
Identifiers
| Name | Type | Description |
|---|---|---|
| merchant_key | MerchantKey | The key of the merchant. |
| shopper_key | ShopperKey | The shopper key as returned by the create-shopper endpoint. |
| token_key | TokenKey | If a specific token details needs to be returned. |
Parameters
| Name | M | Description |
|---|---|---|
| page | O | The page to get. Starts at 0. |
Request Data
Not applicable.
Response Data
Array of:
| Field | Type | M | Description |
|---|---|---|---|
| token_key | UUID | M | The token key generated during token registration. |
| state | Enum(16) | M | The state of the token. It can be 'NEW', 'PENDING', 'VALID', 'DELETED', 'INVALID'. |
| date_created | DateTime | M | The date and time when the token was created. |
| description | String(255) | O | The description of the token. |
| payment_method | Enum(16) | O | The payment method used for the token. |
| last_used | DateTime | O | The date and time when the token was last used. |
| reason | String(1,255) | O | The reason of the state (normally empty). |
| additional_ideal_token_details | Block | C | The ideal token details for a valid ideal token. |
| masked_iban | String(18) | O | The masked IBAN, e.g. 'NL44RABO**6789'. |
| issuer_name | String(1,255) | M | The issuer bank name that the shopper wants to pay, e.g. 'ING Bank N.V.'. |
| issuer_logo_url | URI | M | The issuer logo URL, e.g. 'https://www.ideal.nl/issuer-logos/ing.png'. |
HTTP Status
| Status | Meaning |
|---|---|
| 200 (OK) | Success |
| 401 (Not Authorized) | The merchant is not authorized to execute the request. |
| 403 (Forbidden) | The merchant is not found. |
| 404 (Not Found) | If the specified token was not found. |
Examples
> curl \
-X GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens/252327a1-711b-421a-bf36-4dd34243fde9
< Http 200 OK
< ' {
"token_key" : "252327a1-711b-421a-bf36-4dd34243fde9",
"state" : "VALID",
"date_created" : "2017-02-24T17:08:43Z",
"last_used": "2023-08-07T10:22:50Z",
"payment_method" : "BANCONTACT",
"description": "Bancontact: **** 3002"
}'
> curl \
-X GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens?page=1
< Http 200 OK
< '[ {
"token_key" : "252327a1-711b-421a-bf36-4dd34243fde9",
"state" : "VALID",
"date_created" : "2017-02-24T17:08:43Z",
"last_used": "2023-08-07T10:22:50Z",
"payment_method" : "BANCONTACT",
"description": "Bancontact: **** 3002"
},
{
"token_key" : "11111111-711b-421a-bf36-4dd34243fde9",
"state" : "INVALID",
"date_created" : "2017-02-24T17:08:43Z",
"last_used": "2023-08-07T10:22:50Z",
"payment_method" : "BANCONTACT",
"description": "Bancontact: **** 3002"
},
{
"token_key": "ece01f11-86e5-4bc6-9289-588d7c3ade4e",
"state": "VALID",
"date_created": "2025-08-25T14:51:53Z",
"last_used": "2025-08-25T14:52:04Z",
"payment_method": "IDEAL",
"additional_ideal_token_details": {
"masked_iban": "NL44RABO******6789",
"issuer_name": "NG Bank N.V.",
"issuer_logo_url": "https://www.ideal.nl/issuer-logos/ing.png"
}
]'
Delete a token
The delete token endpoint allows the merchant to mark a token as deleted. After deletion a token can no longer be used.
DELETE /ps/api/public/v1/merchants/{merchant_key}/shoppers/{shopper_key}/tokens/{token_key}
Identifiers
| Name | Type | Description |
|---|---|---|
| merchant_key | MerchantKey | The key of the merchant. |
| shopper_key | ShopperKey | The shopper key as returned by the create-shopper endpoint. |
| token_key | TokenKey | The token key to remove. |
Parameters
Not applicable.
Request Data
Not applicable.
Response Data
Not applicable.
HTTP Status
| Status | Meaning |
|---|---|
| 200 (OK) | Success |
| 401 (Not Authorized) | The merchant is not authorized to execute the request. |
| 403 (Forbidden) | The merchant is not found. |
| 404 (Not Found) | The token was not found. |
Examples
> curl \
-X DELETE \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens/22222222-993a-424d-a769-3ee97116a1b6
< Http 200 Ok
Start Tokenized Payment
There is no separate endpoint for starting a payment with tokenized payment details. The existing start payment endpoint is used to start a tokenized payment. The payment method must be set to TOKEN for tokenized payments and the token_details-block must be filled in. More details about the start payment endpoint can be found in the Payments API section.
POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/payments
Identifiers
| Name | Type | Description |
|---|---|---|
| merchant_key | MerchantKey | The key of the merchant. |
| order_key | OrderKey | The order key associated with the token. |
Parameters
Not applicable.
Request Data
| Field | Type | M | Description |
|---|---|---|---|
| method | PaymentMethod | M | The payment method, in this case 'TOKEN'. |
| authentication_methods | AuthenticationMethod[] | M | The used authentication methods that successfully authenticated the shopper at the webshop. |
| token_details | Block | M | The token details to perform payment. |
| - token_key | UUID | M | The token key. |
| - browser_information | Block | M | Information about what kind of response Browser accepts, User-Agent, and shopper IP. |
| ++ shopper_ip | String(1, 45) | M | IP of the device from which shopper is making payment. This is an IPv4, IPv6, or an 'IPv4-mapped IPv6' address. The address should match the simple regular expression [0-9a-fA-F:.]{1,45}. |
| ++ accept | String(1, 255) | M | Response types which browser accepts like text/html,application/xhtml+xml,application/xml. |
| ++ user_agent | String(1, 255) | M | Browser and Operating System of a System from which Payment is being made. e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363 |
Response Data
Response data and HTTP statuses are the same as the Start Payment Response.
Examples
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/11111111-993a-424d-a769-3ee97116a1b6/tokens \
-d '{
"method": "TOKEN",
"authentication_methods" : ["USER_PASSWORD", "OUT_OF_BAND"],
"token_details": {
"token_key": "e7861525-a430-45bf-8a5b-f2989529ad42",
"browser_information" : {
"shopper_ip" : "0.0.0.0",
"accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
}
}
}'
< Http 201 Created
< '{
"id": "pid1607508003t",
"status": "AUTHORIZED"
}'