# Tokenization

For tokenization several API endpoints are available. For a general description of tokenization and dataflows, see the [Tokenization Guide](https://developers.cm.com/payments-platform/reference/psp-tokenized-payment-details) .

# 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](https://developers.cm.com/payments-platform/reference/psp-api-orders#list-payment-methods) to determine the available payment methods for tokenization and use [Start Payment](https://developers.cm.com/payments-platform/reference/psp-api-payments#start-payment) to complete the token registration.

```text Request Line
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.<br/>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.

```shell Implicit 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"
      }'
```
```shell 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 '{
        "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 \| Wero token details for a valid iDEAL \| Wero 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

```shell Get Token Details
> 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"
        }'
```
```shell Get Tokens
> 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

```shell Delete Token
> 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](https://developers.cm.com/payments-platform/reference/psp-api-payments).

```
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](https://developers.cm.com/payments-platform/reference/psp-api-payments#response-data).

## Examples

```shell Start Token Payment
> 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"
      }'
```