Payment details tokenization allows for storing sensitive payment data inside the payments system, which can then be referenced via reference and used for future payments. This can be useful for creating a payment wallet for a webshop, while not storing locally all the payment method details.

Tokenization is not supported for all payment methods and only the following payment methods are supported:

Bancontact (also called Bancontact Wallet Initiated Payments (WIP)).

A token reference is always associated with a specific shopper and cannot be shared between shoppers. This means that a shopper must be created before calling this API-endpoint, see also Shoppers for more details on how to create a new shopper.

Further, an order is always used during token registration. If no (explicit) order is given, then the system generates an order that can be used for token registration. This (implicit) order will have a value of 2 cents. If value of the (implicit or explicit) order is equal to or below 2 cents, then the no actual money will be transferred from the shopper.

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

Field	Type	M	Description
order_key	String(32)	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

Field	Type	M	Description
id	String(14)	M	The payment identifier.
order_key	String(32)	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.

Token Registration with implicit order example

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

Token Registration with explicit order example

> 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. It is strongly recommended to maintain the association between shoppers and tokens locally.

This endpoint also allows the retrieval of details of a particular 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

Not applicable.

Response

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.

Get Token Details and Get Registered token status example

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

Get Tokens example

> 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

Not applicable.

Response

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.

Delete Token example

> 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 a tokenized payment

There is no separate endpoint for starting a payment with tokenized payment details. Instead, 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 also be filled in.

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

Field	Type	M	Description
method	PaymentMethod	M	The supported payment method, here it is '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.

Response and HTTP Status

Response and HTTP status is the same as to that of Start Payment in Payments.

Start a Token payment example

> 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"
     }
}'
 
< Http 201 Created
<    '{
        "id": "pid1607508003t",
        "status": "AUTHORIZED"
      }'