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 and an FPS QR code. 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¶
A card token can be issued during the payment of an order. When issuing a token, the card details are stored encrypted in QIWI.
To issue a token, 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.
PUT /partner/payin/v1/sites/test-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-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://payment.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: b2b-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 documentation.
Token information can be obtained after successful payment authorization by the issuing bank through one of the following ways:
- Using the payment creation request — get the
createdTokenfield in the response. - Using the authentication completion request — get the
createdTokenfield in the response. - In a notification — get the
payment.tokenDatafield of the notification withtype: PAYMENT.
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 (both POST and PUT method can be used), 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).
POST /partner/payin/v1/sites/test-01/sbp/qrCodes HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-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: b2b-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 documentation.
Please Note
One client identifier in the partner’s system can correspond to the data of only one individual.
Token Deletion¶
To terminate the validity of a payment token, pass the following parameters in the payment token deletion request:
customerAccountId— a unique client identifier in the partner’s system bound to the payment token;token— payment token.
Request and response are provided as an example: for the current format and list of parameters, refer to the API documentation.
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 payment tokens.