Payment Tokenization
Overview
Payment tokenization lets you save a customer's card once and charge it again later, without asking them to re-enter their card details. When the customer saves their card, the Payment Gateway issues a payment token: a reference to that card which you store on your side. To charge the card later, you send the token instead of card details.
Use tokens for:
- One-click checkout — returning customers pay with a saved card instead of typing it in again.
- Recurring payments — you charge a subscription, membership, or installment on schedule, without the customer present.
The customer enters their card only on the QiCard-hosted payment page. Your systems store the token, never the card number.
What you'll learn
| Page | Type | What it covers |
|---|---|---|
| 1. Overview (this page) | Concepts | Terminology, token types, and the lifecycle of a saved card |
| 2. Enable & Save a Card | How-to | Get tokenization enabled on your terminal, then save a card as a token |
| 3. Pay with a Saved Token | How-to | Charge a token, for one-click checkout or recurring payments |
| 4. Block a Token | How-to | Stop a token from being used again |
| 5. Reference | Reference | Every tokenization field, the token object, and token-related error codes |
Key terminology
| Term | Description |
|---|---|
| Payment token | A reference to a saved card, issued by the Payment Gateway, for example 48b85aa5-e7a6-5ccc-9466-703472aa7541. It is only useful together with your terminal credentials. |
| Tokenization | The operation that creates a token. The customer enters their card on the hosted payment page, and the gateway returns a token for it. |
| Non-payment operation | A tokenization that does not charge the customer. It is processed as a 0 IQD operation (nonPaymentOperation: true). |
| Customer-initiated payment | The customer is present and chooses their saved card, for example at checkout. |
| Recurring payment | A payment you start without the customer present, for example a monthly subscription renewal (recurrent: true). |
| Blocking | Disabling a token so that it can no longer be used for payments. |
Token types
When you save a card you choose a token type with the tokenType field. The type decides what you can do with the token later:
| Token type | Authenticated | Customer-initiated payments | Recurring payments |
|---|---|---|---|
AUTH | Yes | Yes | Yes |
NON_RECUR | Yes | Yes | No |
UNAUTH | No | Yes, the customer must authenticate each payment | No |
Which type should I request? Request AUTH if you will ever charge the token without the customer present. If you only need one-click checkout, NON_RECUR is enough.
The gateway never returns a more capable token than the one you request, but it can return a less capable one, depending on how the customer was authenticated when the card was saved. Always read the type of the token you receive, store it with the token, and only use the token for what its type allows.
The lifecycle of a saved card
┌──────────────────────────────────┐
│ 1. Save the card │ POST /api/v1/payment
│ needPaymentToken: true │ customer enters card on formUrl
│ nonPaymentOperation: true │
└─────────────────┬────────────────┘
│ gateway posts the payment object to notificationUrl
▼
┌──────────────────────────────────┐
│ 2. Store the token │ paymentToken.token + .type
│ against your customer │ details.maskedPan
└─────────────────┬────────────────┘
│ later: checkout, or a billing date
▼
┌──────────────────────────────────┐
│ 3. Pay with the token │ POST /api/v1/payment
│ paymentType: PAYMENT_TOKEN │ recurrent: true | false
└─────────────────┬────────────────┘
│ card removed or account closed
▼
┌──────────────────────────────────┐
│ 4. Block the token │ POST /api/v1/token/{token}/block
└──────────────────────────────────┘
- Save the card. Your backend sends a normal payment request but with tokenization flags. The customer enters their card on the hosted payment page
formUrl. You can also save the card while the customer pays for an order, you can control that using thenonPaymentOperationboolean flag. - Store the token. The gateway sends the result to your
notificationUrl, including the token and its type. You store them against your customer, together with the masked card number to show it in your UI. - Pay with the token. Whenever you need to charge the card, your backend creates a payment with the token instead of card details.
- Block the token. When the card should no longer be charged, your backend blocks the token, must be done when user account is removed or deleted.
Tokenization runs through the REST API only, also for mobile apps. Your backend creates the payment with the tokenization flags described in this section, and your app passes the returned paymentId to the SDK's processPayment so the customer can complete the payment. The token arrives at your notificationUrl as usual, and your backend stores it, pays with it, and blocks it.
The SDK's built-in tokenization features are not available to merchants: don't set needPaymentToken or tokenType in PaymentDetails, and don't use getPaymentTokens, blockPaymentToken, or transferPaymentTokens. See the SDK API Reference for processPayment.