Payment Token

The payment token is used for an order payment without entering payment details. To enable this payment method, contact our support team.

Token issuance is supported for a bank card, an FPS QR code, and QIWI Wallet. Token payment can be used:

• on the QIWI payment form;
• on the partner’s form.

The client can pay for an order with a payment token only on the site for which the token was issued. To make the token work on other sites, contact our support team.

Bank Card Token

When issuing a card token, the card details are stored encrypted in QIWI.

A payment token can be issued at one of the following stages of interaction with QIWI:

• card verification;
• order payment.

Issuing a token during card verification

In the card verification request, it is necessary to pass the unique client identifier in the partner’s system in the tokenizationData.account parameter.

Card verification requestResponse to the card verification request

PUT /partner/payin/v1/sites/site-01/validation/card/requests/acd7bf20-22e2-4cbf-a218-38d90e9f29b9 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "cardData": {
        "pan": "1111222233334444",
        "expiryDate": "12/34",
        "cvv2": "123",
        "holderName": "Holder Name"
    },
    "tokenizationData": {
        "account": "account"
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0352ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "account"
    }
}

Request and response are provided as an example: for the current format and list of parameters, refer to the «API Reference» section in the Payment API documentation.

Token information can be obtained after a card verification completion using one of the following methods:

• in the response to the card verification request — see the createdToken field;
• in the card verification status request — see the createdToken field;
• in the CHECK_CARD notification — see the tokenData field.

Issuing a token when paying for an order

In the invoice creation request or payment creation request, it is necessary to pass the following parameters:

• "flags": ["BIND_PAYMENT_TOKEN"] — a flag indicating the binding of the payment token;
• customer.account — the client identifier in the partner’s system.

Invoice Creation Request with Token IssuanceResponse to the Invoice Creation Request with Token IssuancePayment Creation Request with Token IssuanceResponse to the Payment Creation Request with Token Issuance

PUT /partner/payin/v1/sites/test-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
      "currency": "RUB",
      "value": 10.00
  },
  "expirationDateTime": "2024-01-13T14:30:00+03:00",
  "customer": {
      "account":"token12345"
  },
  "customFields": {},
  "flags":["BIND_PAYMENT_TOKEN"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "billId": "893794793973",
    "invoiceUid": "39b5c83f-abcc-3060-952f-31agh5b2012f",
    "amount": {
        "currency": "RUB",
        "value": "10.00"
    },
    "expirationDateTime": "2024-01-13T14:30:00+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2024-01-10T17:44:23+03:00"
    },
    "customer": {
        "account": "token12345"
    },
    "flags": [
        "BIND_PAYMENT_TOKEN"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=39b5c83f-abcc-3060-952f-31agh5b2012f"
}

PUT /partner/payin/v1/sites/test-01/payments/test1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "billId": "1234567890",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
  },
    "paymentMethod" : {
        "type" : "CARD",
        "pan" : "4256000000000078",
        "expiryDate" : "03/24",
        "cvv2" : "123",
        "holderName" : "TESTQIWI"
  },
    "customer": {
        "account": "token123"
  },
    "flags":["BIND_PAYMENT_TOKEN"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "paymentId": "test1234567890",
    "billId": "1234543211237",
    "createdDateTime": "2024-01-10T17:51:51+03:00",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "425600******0078",
        "rrn": "123",
        "authCode": "181218",
        "cardHolder": "TESTQIWI"
    },
    "createdToken": {
        "token": "aa8077be-5398-4389-925e-5aa13192e565",
        "name": "425600******0078",
        "expiredDate": "2024-03-31T00:00:00+03:00"
    },
    "customer": {
        "account": "token123"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2024-01-10T17:51:54+03:00"
    },
    "callbackUrl": "https://test.com",
    "customFields": {
        "customer_account": "token123"
    },
    "flags": [
        "TEST"
    ],
    "paymentCardInfo": {
        "issuingCountry": "643",
        "issuingBank": "Test Bank Name",
        "paymentSystem": "VISA",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "Unknown"
    }
}

Request and response are provided as an example: for the current format and list of parameters, refer to the «API Reference» section in the Payment API documentation.

Token information can be obtained after successful payment authorization by the issuing bank through one of the following ways:

• In the response to the payment creation request — see the createdToken field.
• In the response to the authentication completion request — see the createdToken field.
• In a PAYMENT type notification — see the tokenData field.

Please Note

• One client identifier in the partner’s system can correspond to the data of only one individual.
• An invoice creation request with token issuance can be used without an invoice payment — it is not necessary to send the payment creation request.

FPS QR Code Token

To issue a token for FPS QR code, in the QR code creation request, it is necessary to pass the following parameters:

• tokenizationAccount — a unique client identifier in the partner’s system;
• "flags":["CREATE_TOKEN"] — a flag indicating the need of token creation.

The token can be issued for any QR code type (qrCode.type).

QR Code Creation Request (TOKEN type)Response to QR Code Creation Request (TOKEN type)QR Code Creation Request (DYNAMIC type)Response to QR Code Creation Request (DYNAMIC type)

POST /partner/payin/v1/sites/test-01/sbp/qrCodes HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "qrCodeUid": "Test123",
    "qrCode": {
      "type": "TOKEN",
      "image": {
          "mediaType": "image/png",
          "width": 300,
          "height": 300
      }
    },
  "tokenizationPurpose": "Description with bill binding details",
  "tokenizationAccount": "3e2322",
  "flags": ["CREATE_TOKEN"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "qrCodeUid": "Test123",
    "qrCode": {
        "type": "TOKEN",
        "ttl": 10,
        "image": {
            "mediaType": "image/png",
            "width": 300,
            "height": 300,
            "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
        },
        "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDб",
        "status": "CREATED"
    },
    "tokenizationPurpose": "Description with bill binding details",
    "flags": ["CREATE_TOKEN"],
    "token": {
        "status": "CREATED",
        "value": "a4a312345-6789-1234-a567-89a1234567a0",
        "expiredDate": "2023-08-11T10:10:32+03:00"
    },
    "createdOn": "2022-08-11T20:10:32+03:00"
}

POST /partner/payin/v1/sites/test-01/sbp/qrCodes HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "qrCodeUid": "Test123",
    "amount": {
        "value": 100.00,
        "currency": "RUB"
    },
    "qrCode": {
        "type": "DYNAMIC",
        "image": {
            "mediaType": "image/png",
            "width": 300,
            "height": 300
        }
    },
    "tokenizationPurpose": "Description with bill binding details",
    "tokenizationAccount": "3e2322",
    "redirectUrl": "http://someurl.com",
    "flags": ["CREATE_TOKEN"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "qrCodeUid": "Test123",
    "amount": {
        "value": 100.00,
        "currency": "RUB"
    },
    "qrCode": {
      "type": "DYNAMIC",
      "ttl": 10,
      "image": {
          "mediaType": "image/png",
          "width": 300,
          "height": 300,
          "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
      },
      "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDб",
      "status": "CREATED"
    },
    "redirectUrl": "http://someurl.com",
    "tokenizationPurpose": "Description with bill binding details",
    "flags": ["CREATE_TOKEN"],
    "token": {
        "status": "CREATED",
        "value": "a4a312345-6789-1234-a567-89a1234567a0",
        "expiredDate": "2023-08-11T10:10:32+03:00"
    },
    "createdOn": "2022-08-11T20:10:32+03:00"
}

Request and response are provided as an example: for the current format and list of parameters, refer to the «API Reference» section in the Payment API documentation.

Please Note

One client identifier in the partner’s system can correspond to the data of only one individual.

QIWI Wallet Token

To issue a QIWI Wallet token, follow the steps below:

1. Send a token issue POST request to the URL https://api.qiwi.com/partner/payin-tokenization-api/v1/sites/{siteId}/token-requests. In the URL, specify siteId obtained during connection. In the request JSON body, include the following parameters:

   Parameter	Description
   requestId	Request unique identifier, 1 to 36 characters long. It must be different from the identifiers of all previously created QIWI Wallet token requests within one siteId
   phone	Client QIWI Wallet number
   accountId	A unique client identifier in the partner’s system

   Please Note

   One client identifier in the partner’s system can correspond to the data of only one individual.

   Token Issue RequestResponse to Token Issue Request

   POST /partner/payin-tokenization-api/v1/sites/test-01/token-requests HTTP/1.1
   Accept: application/json
   Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
   Content-type: application/json
   Host: api.qiwi.com
   
   {
       "requestId": "asd1232q77w1e3212",
       "phone": "79022222222",
       "accountId": "token324"
   }
   

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
       "requestId": "asd1232q77w1e3212",
       "status": {
           "value": "WAITING_SMS"
       }
   }
   

   Request and response are provided as an example.

2. Send a POST request to complete the token issuance to the URL https://api.qiwi.com/partner/payin-tokenization-api/v1/sites/{siteId}/token-requests/complete after the client receives an SMS with a one-time code. In the URL, specify siteId obtained during connection. In the request JSON body, include the following parameters:

   Parameter	Description
   requestId	Value of requestId specified in the request from step 1
   smsCode	Code from the SMS received by the client

   Completing Token Issuance RequestResponse to Completing Token Issuance Request

   PUT /partner/payin-tokenization-api/v1/sites/test-01/token-requests/complete HTTP/1.1
   Accept: application/json
   Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
   Content-type: application/json
   Host: api.qiwi.com
   
   {
       "requestId": "asd1232q77w1e3212",
       "smsCode": "1223"
   }
   

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
       "requestId": "asd1232q77w1e3212",
       "status": {
           "value": "CREATED"
       },
       "token": {
           "value": "589c04b5-47dd-41af-9682-b3eb91",
           "expiredDate": "2021-11-08T14:23:54+03:00"
       }
   }
   

   Request and response are provided as an example.

Token Deletion

To terminate the validity of a payment token, send a DELETE request to the URL https://api.qiwi.com/partner/payin/v1/sites/{siteId}/tokens. In the URL, specify siteId obtained during connection. In the request JSON body, include the following parameters:

Parameter	Description
customerAccountId	A unique client identifier in the partner’s system bound to the payment token
token	Payment token

Token Deletion RequestResponse to Token Deletion Request

DELETE /partner/payin/v1/sites/test-01/tokens HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "token": "1a2b3c4d-1a2b-1a2b-1a2b3c-1a2b3c4d5e",
  "customerAccountId": "token_name"
}

HTTP/1.1 204 No Content

Request is provided as an example.

Please Note

• One client identifier in the partner’s system can correspond to the data of only one individual.
• This method is implemented only for card and QIWI Wallet payment tokens.