Tokens

Tokenization eliminates the need for customers to re-enter their card details for subsequent payments, making it ideal for scenarios like subscriptions and other recurring payments. It is primarily used for Merchant Initiated Transactions (MIT).

Use Cases

Area/Feature	Tokenisation Use Case
Payment Page / SDK	Secure card data handling, PCI compliance
Merchant Initiated Terminal	Recurring/subscription payments using stored tokens
Refunds	Reference to original payment token for secure refunds

Tokenization Process

Enabling Tokenization

To enable tokenization during order creation, set the enforceTokenization parameter to true in the Create New Order request.

Example Order with Tokenization:

1 {
2     "terminalId": "123456",
3     "purchaseOrderId": "PO123456789",
4     "companyPurchase": true,
5     "company": {
6         "id": "C12345",
7         "vatId": "VAT67890",
8         "poDetails": "Company purchase order details"
9     },
10     "customer": {
11         "person": {
12             "name": "John Doe",
13             "id": "CU12345",
14             "email": "john.doe@example.com",
15             "phone": {
16                 "extension": "+1",
17                 "phoneNumber": "1234567890",
18                 "personalNumber": "123-45-6789",
19                 "coordinationNumber": "C123456789",
20                 "countryResidence": "US"
21             },
22             "birthDate": "1990-01-01"
23         },
24         "billing": {
25             "careof": "Jane Doe",
26             "address1": "123 Main St",
27             "address2": "Suite 100",
28             "city": "Anytown",
29             "postalCode": "12345",
30             "country": "US"
31         }
32     },
33     "type": "purchase",
34     "referenceId": "REF123456",
35     "orderLines": [
36         {
37             "id": "ITEM123",
38             "name": "Item Name",
39             "description": "Description of the item",
40             "quantity": 2,
41             "itemAmount": {
42                 "regular": 100.0,
43                 "currency": "USD"
44             }
45         }
46     ],
47     "totalOrderAmount": {
48         "regular": 200.0,
49         "currency": "USD"
50     },
51     "controlFunctions": {
52         "enforceTokenization": true
53     }
54 }

Fetching Tokens After Payment

After a successful payment, if enforceTokenization was set to true, you can retrieve all tokens associated with that order using the Tokens API.

$ curl -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      YOUR_API_URL/orders/:orderId/tokens

Storing Tokens

Securely store the retrieved tokenId in your system, linked to the customer who made the payment. This ensures you can easily use the token for future Merchant Initiated Transactions.

Security

Always store tokens securely and never expose them to unauthorized access. Tokens should be associated with customer records in your database.

Token Workflow

Using Tokens for MIT

Once you have stored a token, you can use it for Merchant Initiated Transactions:

$ curl -d '{
>           "orderId": "YOUR_ORDER_ID",
>           "paymentMethod": "CTOKEN",
>           "tokenId": "YOUR_TOKEN_ID"
>          }' \
>      -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      YOUR_API_URL/payments

For detailed MIT implementation, see the MIT Transactions guide.