QIWI
Feedback
bss@qiwi.com
NAV Navbar
Examples

Overview

The Payments protocol provides a payment processing solutions that helps you accept payments in fast and secure way. The protocol gives your customers flexibility to pay the way they want, including:

Terms and Abbreviations

Last update: 2021-08-25 | Edit on GitHub

API Key — String for merchant authentication in API according to OAuth 2.0 standard RFC 6749 RFC 6750.

Payment token — String linked to the card data for payments without entering card details.

API: Application Programming Interface — a set of ready-made methods provided by the application (system) for use in external software products.

REST: Representational State Transfer — a software architectural pattern for Network Interaction between distributed application components.

JSON: JavaScript Object Notation — a lightweight data-interchange format based on JavaScript RFC 7159.

3DS: 3-D Secure — protection protocol used to authenticate card holder while making a payment transaction over the Internet. QIWI supports both 3DS 1.0 version and 3DS 2.0 version of the protocol.

RSP, Merchant — Retail Service Provider.

MPI: Merchant Plug-In — programming module performing 3DS authentication.

PCI DSS: Payment Card Industry Data Security Standard – a proprietary information security standard for storing, processing and transmitting credit card data established by Visa, MasterCard, American Express, JCB, and Discover.

How to Get Started

To start using Protocol, you need to complete the following steps.

Step 1. Leave request to integrate on b2b.qiwi.com

After processing the requests, our personnel contact you to discuss possible ways of integration, collect the necessary documents and start integration process.

Step 2. Get access to your Account

Upon connecting to the Payment Protocol, we provide you the unique site identifier (siteId) and access to your Account in our system. We send the Account credentials to your e-mail address specified on registration.

Step 3. Issue API access key for the integration

API access key is used for interaction with API. Issue API access key in Settings section of your Account.

Step 4. Test the interaction

During integration process, your siteId identifier is in test mode. You can proceed test operations without debiting credit card. See Test and Production Mode for details.

When integration on your side is completed, we turn your siteId to production mode. In the production mode cards are debited.

Ways of Integration

Payment protocol provides several ways of integration:

Available Payment Methods

Method Payment through QIWI Form Payment through merchant form
Credit/debit card
Payment by payment token
Apple Pay
Google Pay
Faster Payments System ×
QIWI Wallet Balance ✓*

* — by issuing a payment token for QIWI wallet

Operation Types

The following operations are available in the protocol:

Payment processing and settlements scheme

sequenceDiagram participant customer as Customer participant store as Merchant participant ipsstore as Bank of
Merchant participant qb as QIWI participant ips as Payment system participant ipscust as Bank of
Customer
Issuer or bank-sender customer->>store:Payment start store->>qb:Payment operation qb->>ips:Payment authorization ips->>ipscust:Payment authorization rect rgb(237, 243, 255) Note over ipsstore, ipscust:Settlements ipscust->>ips:₽₽₽ ips->>qb:₽₽₽ qb->>ipsstore:₽₽₽ end

Interaction format

API of the Payment protocol implements REST principles.

API uses HTTPS-requests for main application protocol.

API endpoint:

https://api.qiwi.com/partner/

API requests' parameters are transferred in the request body JSON data. Parameters in HTTP GET-requests are placed in URL.

API always responds in JSON format.

Authentication

Request with authentication

curl -X PUT https://api.qiwi.com/partner/v1/sites/{site_id}/payments/{payment_id} \
     --oauth2-bearer <API Key>

Authentication header

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

For the requests authentication OAuth 2.0 standard is used in accordance with RFC 6750. Always put API access key value into Authorization HTTP-header as

Bearer <API Key>

Test and Production Modes

During integration, your siteId identifier is in test mode. You can proceed operations without debiting credit card. You can also request a switch to test mode for any of your siteId, or add a new siteId to test mode through your support manager.

For testing purposes, the same protocol URLs are used.

Test mode is not supported for QIWI Wallet balance payments.

When integration on your side is completed, we turn your ID to production mode. In the production mode cards are debited.

You don't need to re-release the API access key when you go into production mode. However, if you change the permanent URL for notifications from a test notification (such as a https://your-shop-test.ru/callbacks) to a production one (such as https://your-shop-prod.ru/callbacks), you need to release a new API access key.

Card payment in test mode

To make tests for payment operations, you may use any card number complied with Luhn algorithm.

Test card numbers

In testing mode, you may use only Russian ruble (643 code) for the currency.

CVV in testing mode may be arbitrary (any 3 digits).

To test various payment methods and responses, use different expiry dates:

Test environment has restrictions on the total amount and number of operations. By default, maximum amount of a test transaction is 10 rubles. Maximum number of test transactions is 100 rubles per day (MSK time zone). Only test transactions within allowed amount are taken into account.

To process 3DS operation, use unknown name as card holder name. 3DS in test mode may be properly tested on real card number only.

Payment through Faster Payments System in test mode

To test various payment methods and responses, use different amounts (amount field):

Payment Through QIWI Form

When you integrate payments through the QIWI form, the default payment method is Bank Cards. The following payment methods are connected on demand:

Payment process

sequenceDiagram participant customer as Customer participant store as Merchant participant qb as QIWI (acquirer) participant ips as Issuer customer->>store:Choose goods, Start payment activate store store->>qb:Issue invoice
One-step payment — all payment methods
Two-step payment — only cards and QIWI Wallet (QW) activate qb qb->>store:URL to QIWI Payment form (payUrl) store->>customer:Redirecting customer to payUrl customer->>qb:Payment form opens,
choose payment method,
enter details for chosen method qb->>customer:Customer authentication:
3DS for cards, QIWI Wallet authorization for QW customer->>qb:Authentication qb->>ips:Request for funds charging activate ips ips->>qb:Operation status qb->>store:Notification with operation status qb->>customer: Redirecting to payment status page (successUrl) rect rgb(237, 243, 255) Note over store, ips:Two-step payment store->>qb:Payment confirmation (capture) qb->>ips:Confirming card charging deactivate ips qb->>store:Notification on payment confirmation end deactivate qb deactivate store

To create invoice for a payment, send in API request Invoice:

or simply redirect customer by the direct link to the QIWI Form.

QIWI Payment Form integration without API

It's an easy way to integrate with the QIWI payment form. When the form is opened, the customer is automatically billed for the order. Parameters of the invoice are sent unprotected in the link. A payment form with a choice of payment methods is shown to the customer.

To integrate, contact Support to obtain the PUBLIC_KEY key and use it in all links to the form. A unique key is produced for each siteId.

When paying an invoice in this way, the payment is authorized without the participation of the merchant. Turn on automatic payment confirmation in Support, so you don't have to comply with the Payment confirmation request.

REDIRECT →

https://oplata.qiwi.com/create?publicKey=e1ZuGvjEoxxGHUz3raU1hZm2LyrSqxt37XGRtQhMWZrkw2VT8truUtaEBpY833Wxand5eX3MUFUcEq5T3eae1GdQQbQBgJwtVciAVG3btyZbLr4KABGrny2&comment=some%20comment&extras[cf1]=custom%20field%201&amount=14.88
Parameter Description Type Required
publicKey Merchant identification key String +
billId Unique invoice identifier in merchant's system. It must be generated on your side with any means. It could be any sequence of digits and letters. Also you might use underscore _ and dash -. If not used, for each URL opening a new invoice is created. URL-encoded string String(200) -
amount Amount of customer order rounded down to 2 digits (always in rubles) Number(6.2) -
phone Customer phone number (international format) URL-encoded string -
email Customer e-mail URL-encoded string -
comment Comment to the invoice URL-encoded string String(255) -
successUrl URL for redirect from the QIWI form in case of successful payment. URL should be within the merchant's site. URL-encoded string -
extras[cf1] Extra field to add any information to invoice data URL-encoded string -
extras[cf2] Extra field to add any information to invoice data URL-encoded string -
extras[cf3] Extra field to add any information to invoice data URL-encoded string -
extras[cf4] Extra field to add any information to invoice data URL-encoded string -
extras[cf5] Extra field to add any information to invoice data URL-encoded string -

By default, the customer is automatically authenticated after the invoice is paid. Authentication is also automatically completed.

Bank card

The payment protocol supports both a two-step payment with holding funds on the customer's card, and a one-step payment without the authentication of the customer.

Invoice creation

Example of invoice creation with payment on hold (two-step payment)

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 42.24
   },
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {}
}

Example of invoice creation with payment without customer authentication (one-step payment)

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "flags": [
              "SALE"
			      ]
}

To create an invoice with payment through holding funds on the card (two-step scenario), pass the API request Invoice:

For the two-step payment, the reimbursement is formed only after the order confirmation.

To pay the invoice without the customer's authentication (one-step scenario), include in the API request Invoice the "flags":["SALE"] parameter. If you do not pass this parameter, the unconditional holding of funds to pay the invoice will be made.

Payment confirmation

Notification example

{
  "payment":{
    "paymentId":"804900",  <==paymentId, необходимый для подтверждения
    "type":"PAYMENT",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":"..",
    "customer":"..",
    "gatewayData":"..",
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

Payment confirmation

PUT /partner/payin/v1/sites/{siteId}/payments/804900/capture/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

This action is required for two-step scenario (payment with holding funds).

To confirm payment:

Payment token

Invoice payable with payment token

PUT /partner/payin/v1/sites/test-02/bills/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {
     "account": "token234"
   },
   "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
   }  
   }
}

The payment tokens are used for charging a customer balance without entering card details or QIWI Wallet number. By default, the use of payment tokens is disabled. Contact your Support manager to enable that.

You can read about the issue of a payment token in this section.

To create an invoice payable with payment token, send in API request Invoice the following data:

If one or more payment tokens have been issued for the customer, the Payment form will display their linked cards.

qiwi-form-tokens

To use the payment token, it is enough for the customer to choose one of their linked cards. Customer doesn't need to provide card data or 3-D Secure authentication.

To charge funds on a payment token without the customer's participation, use the API method Payment. See details in section Using payment token for the mercant's payment form.

Apple Pay/Google Pay

Apple Pay purchases are made without card data entering. The technology works in mobile apps and the Safari browser on iPhone, iPad, Apple Watch and MacBook.

For the Google Pay™ method, Visa and MasterCard payments are supported without entering the card data.

To add Apple Pay/Google Pay payment methods to the QIWI Payment Form, contact your Support manager.

Invoicing and notification of payment for Apple Pay/Google Pay payment methods are similar to bank card payment.

QIWI Wallet

Invoice payable with QIWI Wallet

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 1.00
   },
   "expirationDateTime": "2020-10-16T14:30:00+03:00"
}

By default, the payments from QIWI Wallet balance are turned off. To enable this payment method, contact your Support manager.

To create an invoice payable with QIWI Wallet, send in the API request Invoice for QIWI Wallet payment the following data:

Redirect customer to the Payment form link, which will come in response in the payUrl field. On the Payment form, the customer will have an option to pay from the balance of the QIWI Wallet.

The payment process for the customer is as follows:

  1. The customer opens the form.

    Wallet Invoice

  2. The customer authenticates in QIWI Wallet.

    Wallet Auth

  3. The customer pays for the invoice.

    Wallet Pay

Redirect to QIWI Form

Response with payUrl parameter

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

{
    "siteId": "test-01",
    "billId": "gg",
    "amount": {
        "currency": "RUB",
        "value": 42.24
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-28T16:26:36.835+03:00"
    },
    "customFields": {},
    "comment": "Spasibo",
    "creationDateTime": "2019-08-28T16:26:36.835+03:00",
    "expirationDateTime": "2019-09-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=78d60ca9-7c99-481f-8e51-0100c9012087"
}

After invoice creation, the link to QIWI Form is in payUrl field of the response.

Example of the link with successUrl

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275&successUrl=https://merchant.ru/payments/#introduction

You can add the following parameter to the link:

Parameter Descripton Type
successUrl URL for customer redirection in case of successful payment. Redirect proceeds after the successful 3DS authentication. URL should be UTF-8 encoded. URL-encoded string

By default, 3-D Secure is required on the QIWI Form.

Customization of QIWI Payment Form

Example of calling Custom Payment form

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

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
     "themeCode":"merchant01-style01"
    }
}

Add your style, customizable logo, background, and color of the buttons to the Payment form on the QIWI side. To do so, contact QIWI Support on payin@qiwi.com and provide the following information:

Some optional data are also used:

To use your Custom Payment form, send the alias for the Payment form in "themeCode" field in customFields object of API request Invoice. URL received in payUrl field of the response would display your Custom Payment form.

Customer form

Payment Through Merchant Web Form

When you intergrate payments through your own payment form, Bank Card payment method is available by default. The following payment methods are connected on demand:

Payment process

sequenceDiagram participant customer as Customer participant store as Merchant participant qb as QIWI (acquirer) participant ips as Issuer customer->>store:Choose goods, start payment,
enter card data activate store store->>qb:Платеж
One-step payment — all payment methods
Two-step payment — only cards, Apple Pay, Google Pay activate qb qb->>store:Operation status, 3DS data or
QR code for Faster Payment System rect rgb(237, 243, 255) Note over customer, ips:3-D Secure store->>customer:Redirecting customer to acsUrl or to the bank app activate ips ips->>customer:Customer authentication:
3DS — cards,
Faster Payment System — confirming the operation in the card issuer app customer->>ips:Authentication ips->>store:Result of the authentication (PaRes) store->>qb:Completing authentication ("complete") end qb->>ips:Request for charging funds activate ips ips->>qb:Operation status qb->>store:Notification on the status of the operation rect rgb(237, 243, 255) Note over store, ips:Two-step payment store->>qb:Confirming the operation ("capture") qb->>ips:Confirming card charging deactivate ips qb->>store:Notification on the payment confirmation end deactivate qb deactivate store

To create a payment, send the following data in API request Payment:

Bank Card

The payment protocol supports both a two-step payment with holding funds on the customer's card, and a one-step payment without the authentication of the customer.

Payment creation

Example of a payment with subsequent hold (two-step)

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

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  }
}

Example of a payment with immediate charging without customer authentication (one-step payment)

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

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  },
  "flags": [ "SALE" ]
}

To start payment with subsequent hold of funds on the customer card (two-step payment), send the following data in API request Payment:

For the two-step payment, the reimbursement is formed only after the order confirmation.

For payment without the customer's authentication (one-step payment), include in the API request Invoice the "flags":["SALE"] parameter. If you do not pass this parameter, the unconditional holding of funds for the payment will be made.

Awating the customer authentication (3-D Secure)

Example of response with customer authentication requirement

{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": 1.00
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    },
    "requirements" : {
        "threeDS" : {
          "pareq" : "eJyrrgUAAXUA+Q==",
          "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
        }
    }
}

Redirecting for 3-D Secure authentication

<form name="form" action="{ACSUrl}" method="post" >
        <input type="hidden" name="TermUrl" value="{TermUrl}" >
        <input type="hidden" name="MD" value="{MD}" >
        <input type="hidden" name="PaReq" value="{PaReq}" >
</form>

Finishing customer authentication

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

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}

If bank requires 3DS authentication of the customer, you will need to pass additional authentication from the issuer. In this case, the payment request adds requirements.threeDS JSON-object with fields:

To get the PaReS result of authentication, make a POST query to the 3-D Secure authentication server URL with parameters:

To maintain backward compatibility, using 3-D Secure 1.0 or 3-D Secure 2.0 does not affect your integration with the API.

The customer's information is passed to the card payment system. The issuer bank either grants permission to charge funds without authentication (frictionless flow) or decides whether to authenticate with a single-time password (challenge flow). After the authorization is passed, the customer is redirected to TermUrl URL with the encrypted result of the authentication in the PaRes parameter.

To complete the authentication of the customer, pass on the API request Completing authentication:

Confirm payment

Notification example

{
  "payment":{
    "paymentId":"804900",  <==paymentId required for 'capture'
    "type":"PAYMENT",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

Capture example

PUT /partner/payin/v1/sites/{siteId}/payments/804900/capture/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

The capture step is required only for two-step payments with holding funds.

To confirm payment:

Payment token

Using payment token in a payment request

PUT /partner/payin/v1/sites/test-02/payments/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 2000.00
  },
  "paymentMethod" : {
    "type": "TOKEN",
    "paymentToken" : "66aebf5f-098e-4e36-922a-a4107b349a96"
  },
  "customer": {
        "account": "token324"
  }
}

The payment tokens are used for charging a customer balance without entering card details or QIWI Wallet number. By default, the use of payment tokens is disabled. Contact your Support manager to enable that.

The issue of a payment token is described in this section.

To pay for the customer order with its payment token, send in API request Payment the following data:

Parameter Type Description
paymentMethod.type String Type of the operation. Only TOKEN
paymentMethod.paymentToken String Payment token string
customer.account String Unique ID of the customer in the RSP system for which the payment token was issued. Without this parameter, you cannot pay with the payment token.

Customer won't have to enter its card data and proceed with 3-D Secure authentication.

Apple Pay

Apple Pay purchases are made without card data entering. The technology works in mobile apps and the Safari browser on iPhone, iPad, Apple Watch and MacBook.

To add Apple Pay payment method to the Merchant Payment Form, contact your Support manager.

You need to integrate Merchant Payment form with Apple before starting accept Apple Pay payments. This is required to verify the RSP web-site and receive the customer's payment data. RSP requirements for integrating Apple Pay on the web page:

Visit Apple's website to get more information on integration.

Payment process

The process of making an Apple Pay payment in the API:

  1. Creating an Apple Pay Payment Session.
  2. Validating RSP in Apple Pay.
  3. Getting encrypted payment data from Apple Pay.
  4. Deciphering payment data on the RSP side (optional).
  5. Sending a request for charging to QIWI:
    • with encrypted data;
    • with decrypted data, when Apple payment token is decrypted in the merchant's side.

How to send a payment with encrypted data

Sample 'paymentMethod' JSON-object for Apple Pay payment

"paymentMethod": {
  "type": "APPLE_PAY_TOKEN",
  "paymentData": {
    "version":"EC_v1",
    "data":"IaD7LKDbJsOrGTlNGkKUC95Y+4an2YuN0swstaCaoovlj8dbgf16FmO5j4AX80L0xsRQYKLUpgUHbGoYF26PbraIdZUDtPtja4HdqDOXGESQGsAKCcRIyujAJpFv95+5xkNldDKK2WTe28lHUDTA9bykIgrvasYaN9VWnS92i2CZPpsI7yu13Kk3PrUceuA3Fb6wFgJ0l7HXL1RGhrA7V5JKReo/EwikMsK8AfChK7pvWaB51SsMvbMJF28JnincfVX39vYHdzEwpjSPngNiszGqZGeLdqNE3ngkoEK1AW2ymbYkIoy9KFdXayekELR6hQWnL4MCutLesLjKhyTN26fxBamPHzAf/IczAdWBDq2P/59jheIGrnK30slJJcr1Bocb8rqojyaVZIY+Xk24Nc6dvSdJhfDDyhX56pn5YtWOxWuVOT0tZSJvxBN/HeIuYcNG6R9u7CHpcelsi4I8O+1gruKKZQHweERG2DyCmoUO9zlajOSm",
    "header": {
       "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzLx7FJhw1Z1PmxOLMTQBs1LgKEUT6 hcxLlT8wGrzwyY8tKeG+VPSjryVkTFYECrj+5r28PJWtmvn/unYhbYDaQ==",
       "publicKeyHash":"OrWgjRGkqEWjdkRdUrXfiLGD0he/zpEu512FJWrGYFo=",
       "transactionId":"1234567890ABCDEF"
     },
    "signature":"ZmFrZSBzaWduYXR1cmU="
  }
}

To send payment data to QIWI, specify in the API Payment request body the paymentMethod JSON-object with the following parameters:

How to send a payment with decrypted data

Decrypted cryptogram data fragment

"external3dSec": {
  "type": "APPLE_PAY",
  "onlinePaymentCryptogram": "AOLqt9wP++/WAzN+is7YAoABFA==",
  "eciIndicator": "05"
}

Use this method when Apple Pay payment token is decrypted on your side.

To provide payment data to QIWI, specify in the API Payment request body the paymentMethod JSON-object with the following parameters:

Google Pay

Payments from Visa and MasterCard payment cards are supported for Google Pay™ method.

To add Google Pay™ payment method to the Merchant Payment Form, contact your Support manager.

Steps for Google Pay™ method integration into merchant's Payment Form:

  1. Implement the requirements of Google Pay™ WEB for accepting encrypted payment data. Check Integration checklist for Google Pay™ integration on web-sites and Google Pay™ brand guidelines for web-sites.
  2. To integrate, you need to comply with the data sending requirements: - with encrypted data, - with decrypted data.
  3. Request production access. Indicate the following data in the request:
    • Tokenization Method — Gateway;
    • Payment Processor or Gateway — qiwi;
    • Merchant Name — you need to get it from QIWI Support.
  4. Google will test your Payment Form in production environment and approve the launch.

How to send a payment with encrypted data

Example of JSON-object paymentMethod

"paymentMethod": {
    "type": "GOOGLE_PAY_TOKEN",
    "paymentToken": "eJxVUtuK2zAQfd+vCHGShS9mS0hb8YChjabx……"
    }

Example of encryption/verification for Google Pay payment token

import zlib
import base64

token = 'Hello world'

token_bytes = token.encode('utf-8')
token_deflated = zlib.compress(token_bytes)
token_base64 = base64.b64encode(token_deflated)
token_result = token_base64.decode('utf-8')

resp_base64 = token_result.encode('utf-8')
resp_deflated = base64.b64decode(resp_base64)
resp_bytes = zlib.decompress(resp_deflated)
resp_token = resp_bytes.decode('utf-8')

print('resp_token: ', resp_token)
>> resp_token: 'Hello world'

To send payment data to QIWI, specify in API request Payment JSON-object paymentMethod with the following parameters:

As a result of these Steps, you obtain an encoded string which is the paymentToken field value.

How to send a payment with decrypted data

Example of a payment with decrypted Google Pay cryptogram data

{
  "paymentMethod": {
    "type": "CARD",
    "pan": "4444443616621049",
    "expiryDate": "12/19",
    "holderName": "Google pay",
    "external3dSec": {
      "type": "GOOGLE_PAY",
      "cryptogram": "AOLqt9wP++YAoABFA==",
      "eciIndicator": "05"
    }
  },
  "amount": {
    "value": "5900.00",
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

To send payment data to QIWI, specify in the API request Payment JSON-object paymentMethod with the following parameters:

Faster Payments System

Payment protocol supports charging funds from the customer by Faster Payments System (SBP). With SBP, payment can be made to commercial organizations, including QR-coded ones.

By default, SBP payment method is turned off. To use this method, contact your Support manager.

Receiving QR-code

Exmaple of request for SBP payment

{
 "amount" : {
   "value" : "4.05",
   "currency" : "RUB"
},
 "paymentMethod" : {
    "type" : "SBP"
},
 "comment": "test"
}

Example of response with QR-code

{
  "paymentId": "sbp-test-18",
  "billId": "autogenerated-ef2eccd6-37ce-471d-b0fd-6d2af7085e2e",
  "createdDateTime": "2020-12-11T11:09:48+03:00",
  "amount": {
    "currency": "RUB",
    "value": "4.05"
  },
  "capturedAmount": "..",
  "refundedAmount": "..",
  "paymentMethod": {
    "type": "SBP"
  },
  "requirements": {
    "sbp": {
      "qrcId": "AD10006BTTAGFLUT1HEMP1",
      "image": {
        "mediaType": "image/png",
        "content": "iVBORw0KgAAA5fY51AAAR+.."
      },
      "payload": "https://qr.nspk.ru/AD10006B89A9QD8FLUT1HEMP1?type=02&sum=405&cur=RUB&crc=5C01D"
    }
  },
  "status": {
    "value": "WAITING",
    "changedDateTime": "2020-12-11T11:09:49+03:00"
  }
}

In order for the customer to make a payment through the SBP, release the ЙR-code. To do this, in the API request Payment include the SBP payment method:

"paymentMethod" : { "type": "SBP" }

To add a payment description, use the comment field in the request. If the field in the request is empty, the customer's bank app will show the name of your service as registered in QIWI.

In the response to the request, the JSON object requirements.sbp contains the data of the QR-code:

The QR-code is active for 72 hours and is deactivated after the period ends.

SBP payment status

Example of response for SBP payment status request

{
    "paymentId": "sbp-test-18",
    "billId": "autogenerated-ef2ec7ce-471d-b0fd-6d2af7085e2e",
    "createdDateTime": "2020-12-11T11:09:48+03:00",
    "amount": { .. },
    "capturedAmount": { .. },
    "refundedAmount": { .. },
    "paymentMethod": {
        "type": "SBP"
    },
    "requirements": {
        "sbp": {
            "qrcId": "AD10006BTTAGF4789A9QD8FLUT1HEMP1",
            "payload": "https://qr.nspk.ru/AD10006BTTAGF4789A9QD8FLUT1HEMP1?type=02&sum=405&cur=RUB&crc=5C1D"
        }
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2020-12-11T11:09:49+03:00"
    }
}

After paying for the QR-code, the payment will go to the final status and a notification will be sent.

Without waiting for notification, the status of the payment can be requested through the API.

Server Notifications

Notification example

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-Type: application/json
Signature: j4wnfnzd***v5mv2w=
Host: server.ru

{
   "payment":{
      "paymentid":"4504751",
      "tokendata":{
         "paymenttoken":"4cc975be-483f-8d29-2b7de3e60c2f",
         "expireddate":"2021-12-31t00:00:00+03:00"
      },
      "type":"payment",
      "createddatetime":"2019-10-08t11:31:37+03:00",
      "status":{
         "value":"success",
         "changeddatetime":"2019-10-08t11:31:37+03:00"
      },
      "amount":{
         "value":2211.24,
         "currency":"RUB"
      },
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"220024/*/*/*/*/*/*5036",
         "rrn":null,
         "authCode":null,
         "type":"CARD"
      },
      "paymentCardInfo": {
         "issuingCountry": "810",
         "issuingBank": "QiwiBank",
         "paymentSystem": "VISA",
         "fundingSource": "CREDIT",
         "paymentSystemProduct": "P|Visa Gold"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "customFields":{},
      "flags":[
         "SALE"
      ]
   },
   "type":"PAYMENT",
   "version":"1"
}

QIWI server notification is an incoming HTTP POST request. The JSON-formatted notification message in the request body contains payment/invoice data encoded in UTF-8 codepage.

The Protocol supports the following notification types for API events:

Specify the notification server address in your Personal Profile on kassa.qiwi.com web-site in Settings section. You may also specify the address for a separate operation in optional callbackUrl parameter of API requests.

The URL for notifications should start with https, as notifications are sent by HTTPS to port 443. The site certificate must be issued by a trusted certification center (e.g. Comodo, Verisign, Thawte, etc.)

To make sure the notification is from QIWI, we recommend you to accept messages only from the following IP addresses belonging to QIWI:

To treat notification as successfully delivered, we need your notification server to respond with HTTP code 200 OK. Until this moment, QIWI system will try to resend the notification message several times with growing interval during the day from the operation started.

Notification Authorization

The notification contains a digital signature of the request data which RSP should verify on its side to secure from notification fraud.

The UTF-8 encoded digital signature is placed into HTTP header Signature of the notification message.

To validate the signature, HMAC integrity check with SHA256-hash is used.

Implement the following algorithm to verify notification signature:

  1. Join values of some parameters from the notification with the pipe "|" character as a separator. For example:

    parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value}

    where {*} – notification parameter value. All values are treated as strings. Make sure strings are UTF-8 encoded.

    Signature should be verified for those notification fields:

    • PAYMENT type:payment.paymentId|payment.createdDateTime|payment.amount.value
    • REFUND type:refund.refundId|refund.createdDateTime|refund.amount.value
    • CAPTURE type:capture.captureId|capture.createdDateTime|capture.amount.value
    • CHECK_CARD type: checkPaymentMethod.requestUid|checkPaymentMethod.checkOperationDate
  2. Calculate hash HMAC value with SHA256 algorithm (signature string and secret key should be UTF8-encoded):

    hash = HMAС(SHA256, token, parameters)

    where:

    • token – HMAC hash key. Coincides with the API access key used in the original API request for the operation.
    • parameters – string from step 1.
  3. Compare the notification signature from Signature HTTP-header with the result of step 2. If there is no difference, the validation is successful.

Frequency of notification sending

QIWI notification service sorts unsuccessful notifications on the following queues:

Time of secondary sending notification may slightly shift upward.

PAYMENT Notification Format

Notification field Description Type When present
payment Payment information Object Always
type Operation type String(200) Always
paymentId Payment operation unique identifier in RSP's system String(200) Always
createdDateTime System date of the operation creation URL-encoded string
YYYY-MM-DDThh:mm:ss
Always
amount Object Operation amount data Always
value Operation amount rounded down to two decimals Number(6.2) Always
currency Operation currency (Code: Alpha-3 ISO 4217) String(3) Always
billId Corresponding invoice ID for the operation String(200) Always
status Operation status data Object Always
value Operation status value String Always
changedDatetime Date of operation status update URL-encoded string
YYYY-MM-DDThh:mm:ssZ
Always
reasonCode Rejection reason code String(200) Always
reasonMessage Rejection reason description String(200) Always
errorCode Error code Number Always
paymentMethod Payment method data Object Always
type Payment method type String  
paymentToken Card payment token String When payment token is used for the operation
maskedPan Masked card PAN String Always
rrn Payment RRN (ISO 8583) Number Always
authCode Payment Auth code Number Always
paymentCardInfo Card information Object Always
issuingCountry Issuer country code String(3) Always
issuingBank Issuer name String Always
paymentSystem Card's payment system String Always
fundingSource Card's type (debit/credit/..) String Always
paymentSystemProduct Card's category String Always
customer Customer data Object Always
phone Customer phone number String Always
email Customer e-mail String Always
account Customer ID in RSP system String Always
ip Customer IP address String Always
country Customer country from address string String Always
customFields Fields with additional information for the operation Object Always
cf1 Extra field with some information to operation data String(256) Always
cf2 Extra field with some information to operation data String(256) Always
cf3 Extra field with some information to operation data String(256) Always
cf4 Extra field with some information to operation data String(256) Always
cf5 Extra field with some information to operation data String(256) Always
FROM_MERCHANT_CONTRACT_ID Contract ID between the merchant and the customer String(256) Always
FROM_MERCHANT_BOOKING_NUMBER Booking number for the customer String(256) Always
FROM_MERCHANT_PHONE Phone number of the customer String(256) Always
FROM_MERCHANT_FULL_NAME Full name of the customer String(256) Always
flags Additional API commands Array of Strings. Possible elements — SALE / REVERSAL Always
tokenData Payment token data Object When payment token issue was requested
paymentToken Card payment token String When payment token issue was requested
expiredDate Payment token expiration date. ISO-8601 Date format:
YYYY-MM-DDThh:mm:ss±hh:mm
String When payment token issue was requested
paymentSplits Split payments description Array(Objects) For split payments
type Data type. Always MERCHANT_DETAILS String For split payments
siteUid Merchant ID String For split payments
splitAmount Merchant reimbursement Object For split payments
value Amount of reimbursement Number For split payments
currency Text code of reimbursement currency, by ISO String(3) For split payments
splitCommissions Commission data Object For split payments
merchantCms Commission from merchant Object For split payments
value Amount of commission Number For split payments
currency Text code of commission currency, by ISO String(3) For split payments
orderId Order number String For split payments
comment Comment for the order String For split payments
type Notification type (PAYMENT) String(200) Always
version Notification version String Always

CAPTURE Notification Format

Notification field Description Type
capture Capture information Object
type Operation type String(200)
captureId Capture operation unique identifier in RSP's system String(200)
createdDateTime System date of the operation creation URL-encoded string
YYYY-MM-DDThh:mm:ss
amount Object Operation amount data
value Operation amount rounded down to two decimals Number(6.2)
currency Operation currency (Code: Alpha-3 ISO 4217) String(3)
billId Corresponding invoice ID for the operation String(200)
status Operation status data Object
value Operation status value String
changedDatetime Date of operation status update URL-encoded string
YYYY-MM-DDThh:mm:ssZ
reasonCode Rejection reason code String(200)
reasonMessage Rejection reason description String(200)
errorCode Error code Number
paymentMethod Payment method data Object
type Payment method type String
maskedPan Masked card PAN String
rrn Payment RRN (ISO 8583) Number
authCode Payment Auth code Number
customer Customer data Object
phone Customer phone number String
email Customer e-mail String
account Customer ID in RSP system String
ip Customer's IP address String
country Customer country from address string String
customFields Fields with additional information for the operation Object
cf1 Extra field with some information to operation data String(256)
cf2 Extra field with some information to operation data String(256)
cf3 Extra field with some information to operation data String(256)
cf4 Extra field with some information to operation data String(256)
cf5 Extra field with some information to operation data String(256)
FROM_MERCHANT_CONTRACT_ID Contract ID between the merchant and the customer String(256)
FROM_MERCHANT_BOOKING_NUMBER Booking number for the customer String(256)
FROM_MERCHANT_PHONE Phone number of the customer String(256)
FROM_MERCHANT_FULL_NAME Full name of the customer String(256)
flags Additional API commands Array of Strings. Possible elements — SALE / REVERSAL
type Notification type (CAPTURE) String(200)
version Notification version String

REFUND Notification Format

Notification field Description Type When present
refund Refund information Object Always
type Operation type String(200) Always
refundId Refund operation unique identifier in RSP's system String(200) Always
createdDateTime System date of the operation creation URL-encoded string
YYYY-MM-DDThh:mm:ss
Always
amount Object Operation amount data Always
value Operation amount rounded down to two decimals Number(6.2) Always
currency Operation currency (Code: Alpha-3 ISO 4217) String(3) Always
billId Corresponding invoice ID for the operation String(200) Always
status Operation status data Object Always
value Operation status value String Always
changedDatetime Date of operation status update URL-encoded string
YYYY-MM-DDThh:mm:ssZ
Always
reasonCode Rejection reason code String(200) Always
reasonMessage Rejection reason description String(200) Always
errorCode Error code Number Always
paymentMethod Payment method data Object Always
type Payment method type String Always
maskedPan Masked card PAN String IAlways
rrn Payment RRN (ISO 8583) Number Always
authCode Payment Auth code Number Always
customer Customer data Object Always
phone Customer phone number String Always
email Customer e-mail String Always
account Customer ID in RSP system String Always
ip Customer IP address String Always
country Customer country from address string String Always
customFields Fields with additional information for the operation Object Always
cf1 Extra field with some information to operation data String(256) Always
cf2 Extra field with some information to operation data String(256) Always
cf3 Extra field with some information to operation data String(256) Always
cf4 Extra field with some information to operation data String(256) Always
cf5 Extra field with some information to operation data String(256) Always
FROM_MERCHANT_CONTRACT_ID Contract ID between the merchant and the customer String(256) Always
FROM_MERCHANT_BOOKING_NUMBER Booking number for the customer String(256) Always
FROM_MERCHANT_PHONE Phone number of the customer String(256) Always
FROM_MERCHANT_FULL_NAME Full name of the customer String(256) Always
flags Additional API commands Array of Strings. Possible elements — SALE / REVERSAL Always
refundSplits Refund of split payments description Array(Objects) For refund split payments
type Data type. Always MERCHANT_DETAILS String For refund split payments
siteUid Merchant ID String For refund split payments
splitAmount Data on reimbursement refund for the merchant Object For refund split payments
value Amount of reimbursement refund Number For refund split payments
currency Text code of reimbursement refund currency, by ISO String(3) For refund split payments
splitCommissions Commission data Object For refund split payments
merchantCms Commission from the merchant Object For refund split payments
value Commission amount Number For refund split payments
currency Text code of commission currency, by ISO String(3) For refund split payments
orderId Order number String For refund split payments
comment Comment to the order String For refund split payments
type Notification type (REFUND) String(200) Always
version Notification version String Always

CHECK_CARD Notification Format

Notification field Description Type  
checkPaymentMethod Card verification result Object  
checkOperationDate System date of the operation URL-encoded string
YYYY-MM-DDThh:mm:ssZ
 
requestUid Card verification operation unique identifier String(200) PAYMENT
status Card verification status String  
isValidCard Logical flag means card is valid for purchases Bool  
threeDsStatus Information on customer authentication status. Possible values - PASSED (3-D Secure passed), NOT_PASSED (3-D Secure not passed), WITHOUT (3-D Secure not required)    
paymentMethod Payment method data Object  
type Payment method type String  
maskedPan Masked card PAN String  
cardExpireDate Card expiration date (MM/YY) String  
cardHolder Cardholder name String  
cardInfo Card information Object  
issuingCountry Issuer country code String(3)  
issuingBank Issuer name String  
paymentSystem Card's payment system String  
fundingSource Card's type (debit/credit/..) String  
paymentSystemProduct Card's category String  
createdToken Payment token data Object  
token Card payment token String  
name Masked card PAN for which payment token issued String  
expiredDate Payment token expiration date. ISO-8601 Date format:
YYYY-MM-DDThh:mm:ss±hh:mm
String  
account Customer account for which payment token issued String  
type Notification type String(200)  
version Notification version String  

Refunds and Reversals

Refund and reversal operations are available in the following conditions:

When the payment is refunded, the QIWI commission fee for the payment is not refunded. An exception is if the reversal operation is performed when the payment is refunded. In this case, there is no financial transaction (charging funds from the customer's account) and there is no commission fee.

Refunds on paid invoices

To make a refund on the paid invoice, use the API request Refund.

Refunds on processed payments

A refund on the payment is only possible for a successful payment. The refund can be both partial and complete. In the first case, the entire amount of the accepted payment is refunded. In the second case, only a part of the amount of payment is refunded. Before you request a refund for the payment, check that the payment has been successfully completed and is in SUCCESS status.

To make a refund on a payment, use the API request Refund.

Split Payments

Split payments is a solution developed for marketplaces. Split payments provides a way to pay multiple service providers, making one charging operation from the customer's card.

To connect to split payments:

  1. Contact your Support manager and request access to the solution.
  2. Integrate the solution according to Merchant registration section.

Integration with QIWI Payment form

To send split payments, send in API request Invoice a JSON-array
splits with merchants data.

Data format

Example of invoice request with split payments

curl --location --request PUT 'https://api.qiwi.com/partner/payin/v1/sites/Obuc-02/bills/eqwptt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer token \
--data-raw '{
    "amount": {
        "value": 3.00,
        "currency": "RUB"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "comment": "сomment",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "value": 2.00,
                "currency": "RUB"
            },
            "orderId": "dressesforwhite",
            "comment": "платьица для Тани"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "value": 1.00,
                "currency": "RUB"
            },
            "orderId": "shoesforvalya",
            "comment": "туфельки для Вали"
        }
    ]
}
'

Response example with invoice and split payments

{
    "billId": "eqwptt",
    "invoiceUid": "44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "amount": {
        "currency": "RUB",
        "value": "3.00"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2021-02-05T10:21:17+03:00"
    },
    "comment": "сomment",
    "flags": [
        "TEST"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "currency": "RUB",
                "value": "2.00"
            },
            "orderId": "dressesforwhite",
            "comment": "платьица для Тани"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "1.00"
            },
            "orderId": "shoesforvalya",
            "comment": "туфельки для Вали"
        }
    ]
}

JSON-array splits format:

Name Type Description
splits Array Merchants data array
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement data
value Number Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO. Only RUB value
orderId String Order number (optional)
comment String Comment for the order (optional)

In JSON-object splits of the response the data on split payments and commissions are present:

Response field Type Description
splits Array Array with split payments data
type String Data type. Always MERCHANT_DETAILS
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement data
value String Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO
orderId String Order number
comment String Comment for the order

Integration with Merchant's form

To send split payment, send in API request Payment a JSON-array
paymentSplits with merchants data.

Data format

{
 "paymentMethod": "...",
 "customer": "....",
 "deviceData": "...",
 "paymentSplits": [
   {
     "type":"MERCHANT_DETAILS",
     "siteUid":"shop_mst-01",
     "splitAmount": {
       "value":300.00,
       "currency":"RUB"
     },
     "orderId":"dasdad444ll4ll",
     "comment":"flowers for my girlfriend"
  },
  {
    "type":"MERCHANT_DETAILS",
    "siteUid":"shop_mst-02",
    "splitAmount": {
      "value":200.00,
      "currency":"RUB"
      },
      "orderId":"sdadada887sdDDDDd",
      "comment":"watermelon"
    }
  ]
}

Пример ответа

{
   "paymentId": "23",
   "billId": "autogenerated-2a8fcfab-45cb-43b9-81bd-edf65e0ef874",
   "createdDateTime": "2020-10-12T15:29:12+03:00",
   "amount": {
   "currency": "RUB",
   "value": "100.00"
},
   "capturedAmount": {
   "currency": "RUB",
   "value": "100.00"
},
   "refundedAmount": {
   "currency": "RUB",
   "value": "0.00"
},
   "paymentMethod": "..",
   "status": "..",
   "paymentCardInfo": "..",
   "paymentSplits": [
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-01",
          "splitAmount": {
          "currency": "RUB",
          "value": "30.00"
       },
          "splitCommissions": {
          "merchantCms": {
          "currency": "RUB",
          "value": "10.00"
       }
       },
          "orderId": "313fh1f23j13k1k",
          "comment": "i want to buy some goods"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-02",
          "splitAmount": {
             "currency": "RUB",
             "value": "20.00"
           },
          "splitCommissions": {
               "merchantCms": {
                   "currency": "RUB",
                   "value": "10.00"
                }
            },
          "orderId": "sdadada887sdDDDDd",
          "comment": "watermelon"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-03",
          "splitAmount": {
            "currency": "RUB",
            "value": "50.00"
          },
          "splitCommissions": {
            "merchantCms": {
              "currency": "RUB",
              "value": "10.00"
            }
          },
          "orderId": "dasdad444ll4ll",
          "comment": "flowers for my girlfriend"
       }
    ]
}

JSON-array paymentSplits format:

Name Type Description
paymentSplits Array Merchants data array
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement data
value Number Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO. Only RUB value
orderId String Order number (optional)
comment String Comment for the order (optional)

In JSON-object paymentSplits of the response the data on split payments and commissions are present:

Response field Type Description
paymentSplits Array Array with split payments data
type String Data type. Always MERCHANT_DETAILS
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement data
value String Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO
splitCommissions Object Commission data (optional)
merchantCms Object Commission from the merchant
value String Amount of the commission
currency String(3) Text code of the commission currency, by ISO
orderId String Order number
comment String Comment for the order

Refunds on split payments

After a successful authentication of the charging, a refund is available for the split payment transaction.

Example of refund request

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

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "refundSplits": [
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-01",
    "splitAmount": {
      "value": 30.00,
      "currency": "RUB"
    },
    "orderId": "sdadada887sdDDDDd",
    "comment": "watermelon"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-02",
    "splitAmount": {
      "value": 20.00,
      "currency": "RUB"
    },
   
    "orderId": "313fh1f23j13k1k",
    "comment": "i want to buy some goods"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "flowers for my girlfriend"
  }
  ]
}

Example of response

{
    "refundId": "1",
    "createdDateTime": "2020-10-12T15:32:29+03:00",
    "amount": {
        "currency": "RUB",
        "value": "100.00"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2020-10-12T15:32:30+03:00"
    },
    "refundSplits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-02",
            "splitAmount": {
                "currency": "RUB",
                "value": "20.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "sdadada887sdDDDDd",
            "comment": "watermelon"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "30.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "313fh1f23j13k1k",
            "comment": "i want to buy some goods"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-03",
            "splitAmount": {
                "currency": "RUB",
                "value": "50.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "dasdad444ll4ll",
            "comment": "flowers for my girlfriend"
        }
    ]
}

To send split payments refund, send in API request Refund a JSON-array
refundSplits with merchants refunds. Put the total amount of the refund and the refund amount for each merchant. Both partial and complete refund are supported.

JSON-array refundSplits format:

Name Type Description
refundSplits Array Merchants refunds data array
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement refund data
value Number Amount of reimbursement refund
currency String(3) Text code of reimbursement refund currency, by ISO. Only RUB value
orderId String Order number (optional)
comment String Comment for the order (optional)

In JSON-object refundSplits of the response the data on accepted refunds are present:

Response field Type Description
refundSplits Array Array with refunds data
type String Data type. Always MERCHANT_DETAILS
siteUid String Registered merchant ID
splitAmount Object Merchant reimbursement refund data
value String Amount of reimbursement refund
currency String(3) Text code of reimbursement refund currency, by ISO
splitCommissions Object Commission data (optional)
merchantCms Object Commission from the merchant
value String Amount of the commission
currency String(3) Text code of the commission currency, by ISO
orderId String Order number
comment String Comment for the order

Notifications on split payments and refunds

Notification for a split payments

{
    "payment": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "customFields": {
            "comment": "сomment"
        },
        "paymentCardInfo": {
            "issuingCountry": "643",
            "issuingBank": "Unknown",
            "paymentSystem": "VISA",
            "fundingSource": "UNKNOWN",
            "paymentSystemProduct": "Unknown"
        },
        "type": "PAYMENT",
        "createdDateTime": "2021-02-05T11:29:38+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:29:39+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": "425600******0003",
            "cardHolder": "CARD HOLDER",
            "cardExpireDate": "11/2022"
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [],
        "paymentSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.2,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": "платьица для Тани"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "туфельки для Вали"
            }
        ]
    },
    "type": "PAYMENT",
    "version": "1"
}

Notification for a split payments refund

{
    "refund": {
        "refundId": "42f5ca91-965e-4cd0-bb30-3b64d9284048",
        "type": "REFUND",
        "createdDateTime": "2021-02-05T11:31:40+03:00",
        "status": {
            "value": "SUCCESS",
            "changedDateTime": "2021-02-05T11:31:40+03:00"
        },
        "amount": {
            "value": 3,
            "currency": "RUB"
        },
        "paymentMethod": {
            "type": "TOKEN",
            "paymentToken": "1620161e-d498-431b-b006-c52bb78c6bf2",
            "maskedPan": null,
            "cardHolder": null,
            "cardExpireDate": null
        },
        "customer": {
            "email": "glmgmmxr@qiwi123.com",
            "account": "sbderxuftsrt",
            "phone": "13387571067",
            "country": "yccsnnfjgthu",
            "city": "sqdvseezbpzo",
            "region": "shbvyjgspjvu"
        },
        "gatewayData": {
            "type": "ACQUIRING",
            "authCode": "181218",
            "rrn": "123"
        },
        "billId": "autogenerated-19cf2596-62a8-47f2-8721-b8791e9598d0",
        "flags": [
            "REVERSAL"
        ],
        "refundSplits": [
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-00",
                "splitAmount": {
                    "value": 2,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "dressesforwhite",
                "comment": ""
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": ""
            }
        ]
    },
    "type": "REFUND",
    "version": "1"
}

Notifications for split payments and split payment refunds are formed similarly to the API requests described above:

Merchant registration

For split payments, proceed with the following steps to register your merchant in the API for marketplaces.

Key issue

Request

curl --location --request POST 'https://kassa.qiwi.com/api/users/edge_login' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test@test.com",
"password": "111111111111"
}'

Response

HTTP/1.1 200 OK
Content-Type: application/json
Cookie: TokenTail:11w-www1-wwww1111wwww; 

{
"username": "test@test.com",
"user_uid": "1111ffff-22ss-1111-aaaa-12222weeeeeq",
"status_code": "ACTIVE",
"token_head": "kassa-11ww11ee-11ww-1",
"grants": []
}

To authorize in the API for marketplaces, send POST request to the URL:

https://kassa.qiwi.com/api/users/edge_login

Send the parameters in the request body:

In the response, there will be Bearer-token separated into two parts, for future requests.

To produce Bearer-token, concatenate values from token_head field in the response and Cookie TokenTail. In the example you will get API key:

kassa-11ww11ee-11ww-111w-www1-wwww1111wwww

Obtained token is valid for a month. After a month, you must re-authorize in API.

Possible response statuses:

Transfer data of the merchant

Request example

curl --location --request POST 'https://kassa.qiwi.com/edge/kassa-api/api/requests/v2' \
--header 'accept: application/json' \
--header 'Authorization: Bearer token' \
--data-raw '{
   "partner_name":"test_split",
   "partner_type_code":"FIRM",
   "workflow_code":"RU",
   "request_site":"http://split7_prod.ru",
   "request_site_name":"split7_prod",
   "request_type_code":"PAYIN_SPLIT",
   "request_inn":112121212121,
   "extras":[
      {
         "extra_code":"MARKET_SITE_ID",
         "extra_value":"split7_prod_market"
      },
      {
         "extra_code":"MARKET_CMS",
         "extra_value":"2.00"
      },
      {
         "extra_code":"MERCHANT_CMS",
         "extra_value":"4.30"
      },
      {
         "extra_code":"KPP",
         "extra_value":"112233445"
      },
      {
         "extra_code":"OPER_ACCOUNT",
         "extra_value":1122334456666678900
      },
      {
         "extra_code":"BIC",
         "extra_value":112233445666
      },
      {
         "extra_code":"CORR_ACCOUNT",
         "extra_value":1122334456666678900
      },
      {
         "extra_code":"BANK_NAME",
         "extra_value":"Сбер"
      },
      {
         "extra_code":"CHIEF_NEW",
         "extra_value":"{\"surname\": \"Иванов\", \"name\": \"Иван\",\"patronymic\": \"Иванович\", \"phone\": 79022222222}"
      },
      {
         "extra_code":"CONFIDANT_NEW",
         "extra_value":"{\"surname\": \"Иванов\", \"name\": \"Иван\",\"patronymic\": \"Иванович\", \"phone\": 79022222222}"
      }
   ]
}'

Pass the set of data for the merchant. The set is not complete and will be expanded.

Send a POST request to URL:

https://kassa.qiwi.com/edge/kassa-api/api/requests/v2

The value of the API token is indicated in the HTTP header Authorization, which is formed as

Bearer "Token".

JSON-body request parameters:

Parameter Type Description
partner_name string The name (brand) of the final merchant, Latin letters
partner_type_code string By default, FIRM
workflow_code string By default, RU
request_site string The URL of the site where the goods will be purchased in favor of this merchant as part of the split payments
request_site_name string Site name, Latin letters
request_type_code string By default, PAYIN_SPLIT for registering merchant to split payments
request_inn number Merchant's TIN
extras JSON-object An object containing all the other merchant data, the set is not final. The set of extras is strictly defined.
extras.extra_code string The name of the extra containing merchant data
extras.extra_value string Extra value

JSON-object extras

extra_code Type Description
MARKET_SITE_ID string Marketplace ID, which will be used in split payments
MERCHANT_CMS string The commission in percentages for the merchant under the contract. Rounded to two digits after the comma.
MARKET_CMS string The marketplace commission in percentages. Rounded to two digits after the comma.
KPP number PPC for end-merchant legal entities
OPER_ACCOUNT number Merchant's account
BIC number Bank identifier (BIK) of the merchant
CORR_ACCOUNT number Correspondent account of the merchant
BANK_NAME string Settlement bank name for the merchant
CHIEF_NEW object Company CEO personal data
surname string Surname
name string Name
patronymic string Patronymic
phone number Phone number
CONFIDANT_NEW object Confidant personal data (if any)
surname string Surname
name string Name
patronymic string Patronymic
phone number Phone number

Response

{
"request_uid": "3635e988-a79e-44bd-b6c0-50eb793b4acf",
"partner_uid": "afcf86e0-f354-4e88-9f31-0193f8f182d6"
}

You get the following data in response:

Transfer of documents

Next, you need to pass the package of documents of the merchant. Each document is sent in a separate request.

Send POST request to the URL:

https://kassa.qiwi.com/edge/kassa-api/api/files/upload

Value of API token is present in Authorization header, which is constructed as Bearer "Token".

Request to transfer document

curl --location --request POST 'https://kassa.qiwi.com/edge/kassa-api/api/files/upload' \
--header 'Authorization: Bearer kassa-token \
--header 'Content-Type: multipart/form-data' \
--form 'file=@your_file; type=application/pdf' \
--form 'properties={"request_uid":"c852ae0bf","file_code":"SPLIT_STATEMENT"}; type=application/json'

Request parameters are sent as formData:

Parameter Parameter type Data type Description
fileValueObject formData object JSON-object with description of the document file. It includes parameters:
request_uid — uid of the created application from the previous response
file_code — code of the document (see below the possible codes).
multipartFile formData file Transferred document

Possible codes for the document:

A list of codes will be extended in the future.

Response example

"861d0207-54b3-4e3a-bcfb-6f379f329328"

You get uid of the added extra in response.

Getting information about merchant registration status{#check-merchant-registration}

Example of the current status of registration

{
    "request_id": 17191,
    "request_site": "http://split7_prod.ru",
    "request_site_name": "split7_prod",
    "request_user_message": null,
    "request_manager_message": null,
    "request_inn": "112121212121",
    "request_qiwi_account": null,
    "request_type": {
        "request_type_code": "PAYIN_SPLIT",
        "request_type_name": "Подключение поставщиков по сплитам PayIn",
        "options": []
    },
    "request_status": {
        "request_status_code": "USER_WORK",
        "request_status_name": "Клиент заполняет"
    },
    "request_step": {
        "request_step_code": "PAYIN_SPLIT_START",
        "request_step_name": "Начальная заявка на подключение поставщика",
        "extras": [
            {
                "extra_code": "MARKET_SITE_ID",
                "extra_name": "Ид маркетплейса для сплитов",
                "extra_order": 100,
                "extra_is_unique": true,
                "extra_type_code": "STRING",
                "extra_values": [
                    {
                        "uid": "66ecc03c-dd16-426a-9975-a67d331dc5d0",
                        "value": "split7_prod_market"
                    }
                ]
            },
            {
                "extra_code": "MARKET_CMS",
                "extra_name": "Ставка маркетпейса для сплитов",
                "extra_order": 200,
                "extra_is_unique": true,
                "extra_type_code": "STRING",
                "extra_values": [
                    {
                        "uid": "7fc0a4bd-ee62-4157-8bd3-75d78a3617e1",
                        "value": "2.00"
                    }
                ]
            },
            {
                "extra_code": "MERCHANT_CMS",
                "extra_name": "Ставка мерчанта для сплитов",
                "extra_order": 300,
                "extra_is_unique": true,
                "extra_type_code": "STRING",
                "extra_values": [
                    {
                        "uid": "fd1b0dfa-b04d-43b1-b974-0f161ad76c21",
                        "value": "4.30"
                    }
                ]
            }
        ]
    },
    "request_flow": {
        "next_request_status_code": "USER_WORK",
        "back_request_status_code": null,
        "next_request_step_code": "PAYIN_SPLIT_DOCS",
        "back_request_step_code": null
    },
    "request_uid": "ac523fd1-ff43-46f7-9eea-295ddd22a403",
    "request_updated_dtime": 1611691165406,
     "merchant_site_external_ids": [
        "ereerertu-00"
    ],
    "merchant_uids": [
        "c9e6314a-f6dd-490d-b4c1-8ad659d3699e"
    ],
    "check_failures": []
}

To find out the current status of the merchant registration in the API, send a GET request to the URL:

https://kassa.qiwi.comedge/kassa-api/api/requests?request_uid={application uid}

You get the list of the registration data, the current step, and status of the application.

Field in response Type Description
request_id number Numerical ID of the application.
This ID can be used to contact Support to clarify registration issues.
request_site string Site name that is transferred in the request
request_site_name string Merchant name that is sent in the request
request_user_message string The field is not used
request_manager_message string The field is not used
request_inn string Merchant TIN that is sent in the request
request_qiwi_account string The field is not used
request_type object Service data, description of the type of application.
The following value is always returned
"request_type": {
"request_type_code": "PAYIN_SPLIT",
"request_type_name": "Подключение поставщиков
по сплитам PayIn",
"options": []
}
request_status object JSON-object with information about status of the application.
request_status_code string Status code.
Possible values:
MANAGER_WORK — application pending
REJECTED — application rejected
ACCEPTED — application confirmed, merchant transferred to production environment
request_status_name string Russian name for status.
request_step object The object that characterizes the current step of the application.
request_step_code string Service data
request_step_name string Service data
extras object List of previously transmitted data
extra_code string The name of the extras containing merchant data
extra_name string Russian name of the extras containing merchant data
extra_order number Service data
extra_is_unique bool Service data
extra_type_code string Type of data for the extras
extra_values array of objects Extras value
uid string Internal ID to store this extra value
value string Transferred extras value
request_flow object Service data
request_uid string Uid of the created application
request_updated_dtime number Unix-time date of the last update of the application data and its status
merchant_site_external_ids object An object containing data on the created MerchantSiteId in QIWI processing for the merchant. This ID does not come immediately, you need to repeat this request before receiving the ID, or REJECTED status.
merchant_uids object Service data
check_failures object The field is not used

To track the status of the application, check the value of the request_status.request_status_code field in response:

Payment Token

In Payment protocol card and QIWI Wallet payment tokens generation is supported. The tokens can be used for debiting cards or QIWI Wallet without entering card/wallet details. On issuing payment token, card details are stored securely on QIWI side.

Features

By default, the issue of payment tokens is disabled. Contact your Support manager to enable that.

Card payment token issue

Example of request with invoice and payment token issue

PUT /partner/payin/v1/sites/23044/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": "2021-04-13T14:30:00+03:00",
    "customer": { 
      "account":"token32" 
   }, 
   "customFields": {}, 
   "flags":["BIND_PAYMENT_TOKEN"] 
} 

Example of payment request with payment token issue

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

{
   "amount": {  
     "currency": "RUB",  
     "value": 2211.24
   },
   "customer": {
   	"account": "token324",
    "phone": "79022222222"
   },
   "flags":["BIND_PAYMENT_TOKEN"]
}

Example of response with payment token

{
    "paymentId": "test-022",
    "billId": "autogenerated-c4479bb1-c916-4fba-8445-802592fa8d51",
    "createdDateTime": "2020-03-26T12:22:12+03:00",
    "amount": {
        "currency": "RUB",
        "value": 2211.24
    },
    "capturedAmount": "..",
    "refundedAmount": "..",
    "paymentMethod": "..",
    "createdToken": {
        "token": "66aebf5f-098e-4e36-922a-a4107b349a96",<= payment token
        "name": "411111******1111"
    },
    "customer": {
        "account": "token324",
        "phone": "79022222222"
    },
    "status": ".."
}

To issue a payment token, include additional options in the API request Payment or Invoice (depending on which API you use):

You will receive the card payment token details:

You can also issue a payment token by the API request Card verification. Include tokenizationData.account field with a unique customer ID in the RSP system. Put different account values for different users to ensure the security of customers' card data.

You will receive the card payment token details after complete card verification in createdToken field of the final response.

QIWI Wallet payment token issue

Example of a request with QIWI Wallet payment token issue initiation

POST /partner/payin/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"
}

Response

{
    "requestId": "asd1232q77w1e3212",
    "status": {
        "value": "WAITING_SMS"
    }
}

Example of a request with providing QIWI Wallet payment token

PUT /partner/payin/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"
}

Response

{
    "requestId": "asd1232q77w1e3212",
    "status": {
        "value": "CREATED"
    },
    "token": {
        "value": "589c04b5-47dd-41af-9682-b3eb91",<= payment token
        "expiredDate": "2021-11-08T14:23:54+03:00"
    }
}

To issue a QIWI Wallet payment token, make the following API requests:

  1. Requesting the initiation of the QIWI Wallet's payment token issue.

    Make POST request to the URL:

    /partner/payin/v1/sites/{siteId}/token-requests

    where {siteId} — merchant siteId identifier.

    In the JSON-body of the request specify the parameters:

    • requestId — a unique query identifier (1 to 36 characters). The uniqueness means that the ID should differ from the identifiers of all previously created RSP requests for the issue of a payment token within one siteId.
    • phone — QIWI Wallet number of the customer.
    • accountId — unique customer identifier in your system. Put different accountId values for different users to ensure the security of customers' payment data.
  2. A one-time SMS will be sent to the customer's phone. Include it in the following request to complete the issue of the payment token of the wallet.

    Make POST request to the URL:

    /partner/payin/v1/sites/{siteId}/token-requests/complete

    where {siteId} — merchant siteId identifier.

    In the JSON-body of the request specify the parameters:

    • requestId — the identifier from the initiation request for payment token issue.
    • smsCode — a code from SMS sent to the customer.

In response, you get payment token data:

Removal of the payment token

Delete payment token

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": "66aebf5f-098e-4e36-922a-a4107b349a96",
   "customerAccountId": "token324"
}

The method disables a payment token. It applies both to the card payment token and the QIWI wallet payment token.

To disable a payment token, make a DELETE request to the URL:

/partner/payin/v1/sites/{siteId}/tokens

In the JSON-body of the request specify the parameters:

A successful response means that the payment token for the specified customer is no longer valid.

Card Verification

In Payment protocol merchant can use a verification service to check for customer's card details, its validity and availability for purchases. Funds on cardholder's account are not debited until card recurring is confirmed or payment transaction is initiated.

If card verification is passed successfully, payment token can be issued for the card.

By default, access to the verification service is disabled. Contact your Support manager to enable that.

How to use service with QIWI Payment Form

Request to issue invoice with card verification

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

{
    "expirationDateTime": "2023-09-14T14:30:00+03:00",
    "customer": {
        "account":"test-123"
    },
    "flags": ["CHECK_CARD","BIND_PAYMENT_TOKEN"]
}

Successful response body

{
    "siteId": "site-01",
    "billId": "892323232111",
    "amount": {
      "value": 0.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2021-08-13T15:43:41"
    },
    "creationDateTime": "2021-08-13T15:43:41",
    "expirationDateTime": "2023-09-14T14:30:00",
    "payUrl": "https://oplata.qiwi.com/validation/card?invoiceUid=fxxxxx-854c-4e56-xxxx-eb49aef2xxxx"
}

Notification with card verification result

{
   "checkPaymentMethod":{
      "status":"SUCCESS",
      "isValidCard":true,
      "threeDsStatus":"WITHOUT",
      "cardInfo":{
         "issuingCountry":"0",
         "issuingBank":"not present",
         "paymentSystem":"VISA",
         "fundingSource":"UNKNOWN",
         "paymentSystemProduct":"UNKNOWN"
      },
      "createdToken":{
         "token":"xxxxxxx-a53a-4de1-8aa4-xxxxxxx",
         "name":"411111******1111",
         "expiredDate":"2021-11-30T00:00:00+03:00",
         "account":"some_account"
      },
      "requestUid":"uuuuuu-84f6-4044-9dd1-ddddddddd",
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"411111******1111",
         "cardHolder":"",
         "cardExpireDate":"11/2021"
      },
      "checkOperationDate":"2021-08-13T15:44:01+03:00"
   },
   "type":"CHECK_CARD",
   "version":"1"
}
  1. Send invoice request with additional parameter "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"]. For payment tokent generation, set customer.account parameter with unique customer identifier in the mechant's system. Do not specify invoice amount in the request.
  2. Redirect customer to the Payment Form — reference URL comes in payUrl field of the response.
  3. On the Payment Form, customer provides card detaisl and submits for verification. On the form, 3-D Secure authentification performs for customer. check card

  4. When verification finishes, you get CHECK_CARD notification with the result. Information about card accessible for purchases is in isValidCard field (true — card number is valid and card can be purchased). Payment token data is returned in createdToken field of the notification.

How to use service with API

Request with card verification

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": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}

Successful response body

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

Response with 3DS authentification

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "WAITING_3DS",
    "requirements": {
        "pareq": "Some string pareq",
        "acsUrl": "http://xxxxxxx"
    }
}

Response with verification error

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "ERROR"
}

Request to finish 3DS in card verification

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

{
    "pares": "Some string pares"
}

Response

{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}
  1. Send "Check card" request. Put unique verification identifier in requestUid field. For payment token generation, set tokenizationData.account parameter to unique customer's identifier in the merchant's system.
  2. In the response, card verification result returns in isValidCard field (true means card is valid for purchases). Payment token data return in createdToken JSON object.

To make sure that the cardholder themselves entered card number, you can use 3-D Secure additional authentification in the card verification service. Request enabling or disabling 3-D Secure (3DS) procedure by QIWI support. If 3DS is enabled, you receive "requirements" objject with ACS URL for customer redirect (in this case, status field has "WAITING_3DS" value).

Verification scenario is similar to payment operation:

  1. Redirect customer to authentification page.
  2. Finish 3-D Secure by "Complete 3DS on card verification" request. Specify the same requestUid from the initial card verification request.
  3. If 3-D Secure check is finished successfully, isValidCard field contains information about card validity (true means card is valid for purchases). Payment token data return in createdToken JSON object.

Acts

The act on accepted payments for RSP is formed monthly on the second working day of the month.

Download the act template

The act is first sent to an email specified at the registration of the RSP in the service. After confirmation by a partner, the authorized person of QIWI Bank signs the Act in the document system with electronic signature. The signed Act is sent to the legal address of the partner.

Reports

The report with the list of daily operations is sent after 14:00 MSK on weekdays. It contains information only about successful payments processed by the bank. The report is fully compliant with the Act.

The report is sent to the email, specified at the registration of the RSP in the service, in the zip-archive attached in the letter.

The report format

Sample report fragment

BANK_DATA_DOC;BANK_VALUE_DOC;BANK_AGR_CODE;SUM_BANK;TRANS_DATE;TRANSACTION_ID;SUM;COMMISSION;USER_INFO;ID;MERCH;MERCH_SITE;PARENT_TRANSACTION_ID;BILL;PURPOSE;MERCHANT_SITE_NAME;PAYMENT_METHOD_TYPE;ММВБ;CLIENT_AMOUNT;CLIENT_CUR_CODE;SETTLEMENT_AMOUNT;PAYMENTDETAILS
27.08.2020;27.08.2020;3456144;-25676786,28;;;25676786,28;;;;;;;;SETTLEMENT;;;null;;;;
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 9:59;659720;2165,46;25;533669******4030;68860745;hthi;hthi-26;;autogenerated-67cd0dfb-ca5a-0baf-b0e0-735a880c0dac;Оплата;сайт;Bank card;null;2165,46;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:01;660540;1530;25;536809******4077;68860893;hthi;hthi-26;;autogenerated-90870507-acd9-0056-80f7-d050560fba09;Оплата;сайт;Bank card;null;1530;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 10:06;665760;3150;56,7;547007******4635;68861159;hthi;hthi-54;;autogenerated-8a30690b-8c0c-0808-a0bb-6c73cbfdf953;Оплата;сайт;Bank card;null;3150;643;25664068,85;Перевод принятых денежных средств по Договору  от 2019-09-24 00:00:00. Комиссия  руб. НДС не облагается.
27.08.2020;27.08.2020;34562014;243767,27;26.08.2020 

File with report has CSV format.

Download sample report

Report field Description
BANK_DATA_DOC The date of the document affecting the balance of the bank account is drawn up by the Act at the end of the month
BANK_VALUE_DOC The date of the actual change in the balance of the bank account
BANK_AGR_CODE Bank code, unique document number
SUM_BANK Amount of document operations
TRANS_DATE The date of the operation
TRANSACTION_ID Operation number
SUM Amount of the operation
COMMISSION Commission for the operation from the merchant
USER_INFO Masked card number or phone number (in case of QIWI Wallet payment)
ID paymentId operation number on the mercant's side
MERCH Merchant ID
MERCH_SITE Merchant siteId identifier
PARENT_TRANSACTION_ID Refunds include the number of the original payment operation
BILL Invoice ID
PURPOSE Bank operation type: CHARGEBACK/ REVERT_CHARGEBACK/ Оплата/ Возврат/ OPERATION+/ OPERATION-/ SETTLEMENT
MERCHANT_SITE_NAME Merchant site URL
PAYMENT_METHOD_TYPE Payment method: Bank card/ QIWI_WALLET/ SBP
ММВБ Currency rate of MIMB at the time of payment for foreign exchange transactions
CLIENT_AMOUNT The amount of charging from the customer
CLIENT_CUR_CODE Currency of charging from the customer
SETTLEMENT_AMOUNT The amount of the payment order sent to the partner's checking account
PAYMENTDETAILS The purpose of a payment order sent to the partner's checking account (Example: Transfer of accepted funds under the Contract' xxx from yyy. VAT is not subject to/taxed.)

Reimbursement

By default, we make reimbursement for processed operations to merchants once every two days when 10,000 rubles reached. If you need a custom schedule for reimbursements, contact your personal support manager.

QIWI holds a commission for each confirmed operation. If operation is cancelled before the confirmation, commission will not hold. If partial refund is made before the confirmation, commission will be recalculated.

Statuses, Types of the Operations, and Error Codes

Error codes

The Payment Protocol uses the following HTTP-codes of errors for API requests:

Error Code Meaning
400 Bad Request — Your request is invalid (error in request' data or format).
401 Unauthorized — Your API access key is wrong.
403 Forbidden — Access to API is forbidden.
404 Not Found — The specified resource could not be found.
405 Method Not Allowed — You tried to create a payment with an invalid method.
406 Not Acceptable — Your request' data format isn't JSON.
410 Gone — The resource requested has been removed from our servers.
429 Too Many Requests — You are sending requests too frequently.
500 Internal Server Error — We had a problem with our server. Try again later. If response body is empty, repeat the request with the same parameters. If the body is non-empty, make payment status request/invoice status request.
502 Bad Gateway — No connection to service
503 Service Unavailable — We're temporarily offline for maintenance. Please try again later.

Operation types

Operation type is returned in {operation}.type field of the notification.

Operation type Description
PAYMENT The payment. There can be field flag: [ "SALE" ] (one-step payment) or flag: [ "AUTH" ] (two-step payment with holding funds) in the notification.
CAPTURE Operation of the payment confirmation.
REFUND Operation of the refund. There can be field flag: [ "REVERSAL" ] in the notification. It means that there was no financial operation (charging from customer's account) and commission fee would not be hold.

Operation statuses

Operation status reflects its current state.

API returns synchronous status of the operation in the field status.value of the response.

Status in notifications is in the field {operation}.status.value.

In the following table all possible statuses and corresponding operation types, where each status is used.

Operation status Operation type Status description Where it is returned
WAITING PAYMENT Awaiting for 3DS authentication API responses
DECLINE PAYMENT Request for authentication is rejected Notifications, API responses
DECLINE REFUND Request for refund is rejected Notifications, API responses
DECLINE CAPTURE Request for payment confirmation is rejected Notifications, API responses
SUCCESS PAYMENT Request for authentication is successfully processed Notifications
COMPLETED PAYMENT Request for authentication is successfully processed API responses
SUCCESS REFUND Request for refund is successfully processed Notifications
COMPLETED REFUND Request for refund is successfully processed API responses
SUCCESS CAPTURE Request for payment confirmation is successfully processed Notifications
COMPLETED CAPTURE Request for payment confirmation is successfully processed API responses

API errors reference

API errors describe a reason for rejection of the operation. API errors are present:

API error Description
INVALID_STATE Incorrect transaction status
INVALID_AMOUNT Incorrect payment amount
DECLINED_BY_MPI Rejected by MPI
DECLINED_BY_FRAUD Rejected by fraud monitoring
GATEWAY_INTEGRATION_ERROR Acquirer integration error
GATEWAY_TECHNICAL_ERROR Technical error on acquirer side
ACQUIRING_MPI_TECH_ERROR Technical error on 3DS authentication
ACQUIRING_GATEWAY_TECH_ERROR Technical error
ACQUIRING_ACQUIRER_ERROR Technical error
ACQUIRING_AUTH_TECHNICAL_ERROR Error on funds authentication
ACQUIRING_ISSUER_NOT_AVAILABLE Issuer error. Issuer is not available at the moment
ACQUIRING_SUSPECTED_FRAUD Issuer error. Fraud suspicion
ACQUIRING_LIMIT_EXCEEDED Issuer error. Some limit exceeded
ACQUIRING_NOT_PERMITTED Issuer error. Operation not allowed
ACQUIRING_INCORRECT_CVV Issuer error. Incorrect CVV
ACQUIRING_EXPIRED_CARD Issuer error. Incorrect card expiration date
ACQUIRING_INVALID_CARD Issuer error. Verify card data
ACQUIRING_INSUFFICIENT_FUNDS Issuer error. Not enough funds
ACQUIRING_UNKNOWN Unknown error
BILL_ALREADY_PAID Invoice is already paid
PAYIN_PROCESSING_ERROR Payment processing error

API Method Reference

Invoice

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
   }
}
{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2018-03-05T11:27:41"
    },
    "comment": "Text comment",
    "customFields": {
      "cf1": "Some data",
      "FROM_MERCHANT_CONTRACT_ID": "1234"
    },
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Invoice for QIWI Wallet payment

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {}  
   }
}
{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2018-03-05T11:27:41"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Invoice status

[
    {
        "paymentId": "12600406",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:31:49+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQX7gM3fq+hNqO0oI5prexilN1UDEMwl6FcHZZ19m7v63DtRY=",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINE",
            "changedDateTime": "2020-03-26T19:32:09+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12600433",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:32:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINE",
            "changedDateTime": "2020-03-26T19:32:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12601084",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:46:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "rrn": "008692274763",
            "authCode": "242847",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2020-03-26T19:46:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        },
        "flags": [
            "AFT"
        ]
    }
]
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Payment

{
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "amount": {
    "currency": "RUB",
    "value": 200.00
  },
  "billId": "string",
  "customer": {
    "account": "string",
    "address": {
      "city": "Moscow",
      "country": "Russian Federation",
      "details": "Severnoe chertanovo microdistrict 1a 1",
      "region": "Moscow city"
    },
    "email": "customer@example.com",
    "phone": "+79991234567"
  },
  "deviceData": {
    "datetime": "2017-09-03T14:30:00+03:00",
    "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p",
    "ip": "127.0.0.1",
    "screenResolution": "1280x1024",
    "timeOnPage": 1440,
    "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
  },
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "customFields": {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
  },
  "flags": [
    "SALE"
  ]
}
{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "paymentCardInfo": {
    "issuingCountry": "810",
    "issuingBank": "QiwiBank",
    "paymentSystem": "VISA",
    "fundingSource": "CREDIT",
    "paymentSystemProduct": "P|Visa Gold"
  },
  "customFields" : {
    "cf1": "Some data",
    "FROM_MERCHANT_CONTRACT_ID": "1234"
  },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Payment status

{
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Completing authentication

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}
{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "COMPLETED",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Payment confirmation

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example capture"
}
{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Payment confirmation status

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Refund

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}
{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Refund status

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

All refunds status

[
 {
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
 }
]
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Card verification

GET /partner/payin/v1/sites/test-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": "Super Man"
    },
    "tokenizationData": {
        "account": "cat_girl"
    }
}
{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "WITHOUT",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Complete 3DS on card verification

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

{
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
}
{
    "requestUid": "acd7bf20-22e2-4cbf-a218-38d90e9f29b9",
    "status": "SUCCESS",
    "isValidCard": true,
    "threeDsStatus": "PASSED",
    "checkOperationDate": "2021-07-29T16:30:00+03:00",
    "cardInfo": {
        "issuingCountry": "RUS",
        "issuingBank": "Qiwi bank",
        "paymentSystem": "VISA",
        "fundingSource": "DEBIT",
        "paymentSystemProduct": "Platinum..."
    },
    "createdToken": {
        "token": "1a77343a-dd8a-11eb-ba80-0242ac130004",
        "name": "111122******4444",
        "expiredDate": "2034-12-01T00:00:00+03:00",
        "account": "cat_girl"
    }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

Electronic Receipt Transfer (by Fed.Rule 54)

To work on 54-FZ Rule, the Payment Protocol provides a tool to interact with your online cash register. Information to form a fiscal check is passed on to the JSON-object cheque of invoice and payment operation API requests.

To activate the fiscal check service, contact your Support manager with the TIN number with which your organization is registered in the online cash rental service.

For ATOL service, provide the following data also:

JSON-object description

{
 ...
 "cheque" : {
  "sellerId" : 3123011520,
	"customerContact" : "Test customer contact",
  "chequeType" : "COLLECT",
	"taxSystem" : "OSN",
	"positions" : [
    {
      "quantity" : 1,
      "price" : {
        "value" : 7.82,
        "currency" : "RUB"
      },
      "tax" : "NDS_0",
      "paymentSubject" : "PAYMENT",
      "paymentMethod" : "FULL_PAYMENT",
      "description" : "Test description"
    }
	]
 }
}
Parameter Req. Type Description
sellerId Y Number Organization's TIN
chequeType Y Number Cash operation (1054 fiscal tag):
COLLECT – Incoming cash
COLLECT_RETURN - Cash return
CONSUME - Outcoming cash
CONSUME_RETURN - Outcoming cash return
customerContact Y String(64) Customer's phone or e-mail (fiscal tag 1008)
taxSystem Y Number Tax system (fiscal tag 1055):
OSN - General, "ОСН"
USN – Simplified income, "УСН доход"
USN_MINUS_CONSUM – Simplified income minus expense, "УСН доход - расход"
ENVD – United tax to conditional income, "ЕНВД"
ESN - United agriculture tax, "ЕСН"
PATENT – Patent tax system, "Патент"
positions Y array Commodities list
quantity Y Number Quantity (fiscal tag 1023)
price Y Number One item price, with discounts and extra charges (fiscal tag 1079)
tax Y Number VAT rate (fiscal tag 1199):
NDS_CALC_18_118 - VAT rate 18% (18/118)
NDS_CALC_10_110 – VAT rate 10% (10/110)
NDS_0 – VAT rate 0%
NO_NDS – VAT not applicable
NDS_CALC_20_120 – VAT rate 20% (20/120) (20/120)
description Y string(128) Name
paymentMethod Y Number Cash type (fiscal tag 1214):
ADVANCED_FULL_PAYMENT – payment in advance 100%. Full payment in advance before commodity provision
PARTIAL_ADVANCE_PAYMENT – payment in advance. Partial payment before commodity provision
ADVANCE – prepayment
FULL_PAYMENT – full payment, taking into account prepayment, with commodity provision
PARTIAL_PAYMENT – partial payment and credit payment. Partial payment for the commodity at the moment of delivery, with future credit payment.
CREDIT – credit payment. Commodity is delivered with no payment at the moment and future credit payment is expected.
CREDIT_PAYMENT – payment for the credit. Commodity payment after its delivery with future credit payment.
paymentSubject Y Number Payment subject (fiscal tag 1212):
COMMODITY – commodity except excise commodities (name and other properties describing the commodity).
EXCISE_COMMODITY – excise commodity (name and other properties describing the commodity).
WORK – work (name and other properties describing the work). .
SERVICE – service (name and other properties describing the service).
GAMBLING_RATE – gambling rate (in any gambling activities).
GAMBLING_PRIZE – gambling prize payment (in any gambling activities)в.
LOTTERY_TICKET – lottery ticket payment (in accepting payments for lottery tickets, including electronic ones, lottery stakes in any lottery activities).
LOTTERY_PRIZE – lottery prize payment (n any lottery activities).
GRANTING_RESULTS_OF_INTELLECTUAL_ACTIVITY – provision of rights to use intellectual activity results.
PAYMENT – payment (advance, pre-payment, deposit, partial payment, credit, fine, bonus, reward, or any similar payment subject).
AGENCY_FEE – agent's commission (in any fee to payment agent, bank payment agent, commissioner or other agent service).
COMPAUND_PAYMENT_SUBJECT – multiple payment subject (in any payment constituent subject to any of the above).
OTHER_PAYMENT_SUBJECT – other payment subject not related to any of the above.