Tokenization Reference

Every tokenization request uses the Basic Auth or Signature-based authentication and the X-Terminal-Id header, like all Payment Gateway API calls.

Endpoints

Operation	Method and path	Guide
Save a card (tokenize)	POST /api/v1/payment	Enable & Save a Card
Pay with a saved token	POST /api/v1/payment	Pay with a Saved Token
Block a token	POST /api/v1/token/{token}/block	Block a Token

Request fields

These fields are added to the standard Create Payment request body, except token, which is a path parameter of the block call.

Field	Type	Used in	Description
needPaymentToken	boolean	Save a card	Set to true to ask the Payment Gateway to generate a payment token (a reusable reference to the payer's card) from this operation. It must be true when nonPaymentOperation is true.
tokenType	string	Save a card	The type of token requested, in descending order of capability: AUTH - an authenticated token that can be used for any operation, including recurring payments. NON_RECUR - an authenticated token that can be used for any operation except recurring payments. UNAUTH - an unauthenticated token that can only be used in operations where the payer authenticates. You never receive a more capable token than the one you request, but you can receive a less capable one depending on how the payer was authenticated, so always check the type of the returned token.
nonPaymentOperation	boolean	Save a card without a charge	Set to true to save (tokenize) the payer's card without charging it. The operation is processed as a 0 IQD payment, so amount must not be sent, and needPaymentToken must be true.
recurrent	boolean	Pay with a token	Set to true when you charge a saved token as a recurring, merchant-initiated payment (for example a subscription renewal) without the payer present. Recurring payments require an AUTH token. Omit it or set it to false for payments the payer starts.
paymentData	object	Pay with a token	The payment method to use. To charge a saved card, set paymentType to PAYMENT_TOKEN and paymentToken to the token value.
paymentData.paymentType	string	Pay with a token	The payment method. Use PAYMENT_TOKEN to pay with a previously saved token.
paymentData.paymentToken	string	Pay with a token	The token value you received when the payer's card was tokenized. Maximum 100 characters.
token (path)	string	Block a token	The payment token to block: the same value you send as paymentData.paymentToken when paying with the token.

Token types

Token type	Authenticated	Customer-initiated payments	Recurring payments (recurrent: true)
AUTH	Yes	Yes	Yes
NON_RECUR	Yes	Yes	No
UNAUTH	No	Yes, the customer must authenticate each payment	No

The token you receive is never more capable than the tokenType you request, but it can be less capable, depending on how the customer was authenticated. Always check paymentToken.type.

The paymentToken object

After a successful tokenization, the payment object sent to your notificationUrl and returned by Get Payment Status includes a paymentToken object:

"paymentToken": {
  "token": "48b85aa5-e7a6-5ccc-9466-703472aa7541",
  "type": "AUTH",
  "validTo": "2032-01-31",
  "blocked": false
}

Field	Type	Description
token	string	The token value. Store it against your customer and send it as paymentData.paymentToken to charge the card later.
type	string	The type of the issued token: AUTH, NON_RECUR or UNAUTH. It can be lower than the tokenType you requested, so check it before using the token.
validTo	string	The date until which the token can be used.
blocked	boolean	true if the token has been blocked and can no longer be used for payments.

Token error codes

When a token request fails, the response's error object contains one of the standard API Error Codes. These codes are specific to tokens:

Code	Error name	What to check
31	TOKEN_NOT_FOUND	The gateway has no token with this value. Send the token exactly as you received it in paymentToken.token, to the same terminal and environment (sandbox or production) that issued it.
32	TOKEN_PROCESS_NOT_ALLOWED	The token's type does not allow this operation, for example a recurring payment (recurrent: true) with a token that is not AUTH. Check paymentToken.type before you charge a token.
35	INVALID_TOKEN_TYPE	The tokenType value is not one of AUTH, NON_RECUR, or UNAUTH. Check the spelling and use upper case.

Terminal permissions

If tokenization requests fail even though the request matches this guide, check with the Payment Gateway team that tokenization is enabled on your terminal. See Step 1 — Enable tokenization on your terminal.