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.

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).

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"
       }
 
]'

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"
      }'