QIWI
Feedback
bss@qiwi.com
NAV Navbar
Examples

Overview

Last update: 2022-12-08 | Doc version 1.18 | Edit on GitHub

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

API Key — String for merchant authorization 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 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 customer 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
Faster Payments System
QIWI Wallet Balance ✓**
Mobile phone account ×

* — default payment method, other methods are available upon request.

** — 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(255, 238, 223) 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.

Authorization

Request with authorization

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

Authorization header

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

For the requests authorization 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 manager in QIWI Support.

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.

If necessary, change the permanent URL for notifications from a test notification (such as https://your-shop-test.ru/callbacks) to a production one (such as https://your-shop-prod.ru/callbacks) in your Account Profile.

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 payment amounts (amount field):

Payment Through QIWI Form

When you integrate payments through the QIWI form, the only available payment method is by bank cards. The following payment methods are enabled on demand:

To create invoice for a payment, use API to issue an invoice or simply redirect customer to the QIWI Form by the direct link with the invoice data.

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:API: Invoice request
One-step payment — all payment methods
Two-step payment — only cards activate qb qb->>store:Response with QIWI Payment form URL (payUrl) store->>customer:Redirecting customer to payUrl customer->>qb:Open Payment form,
choose payment method,
enter details for chosen method qb->>customer:Customer authentication:
3-D Secure for cards customer->>qb:Authentication qb->>ips:Request for funds charging activate ips ips->>qb:Operation status qb->>store:Notification with operation status qb->>customer: Return to the merchant site on successful payment (successUrl) store->>qb: Check operation status
API: Payment status request qb->>store: Operation status rect rgb(255, 238, 223) Note over store, ips:Two-step payment store->>qb:Payment confirmation
API: Payment confirmation request qb->>ips:Confirming card charging deactivate ips qb->>store:Notification on payment confirmation store->>qb: Check operation status
API: Payment confirmation status request qb->>store: Operation status end deactivate qb deactivate store

QIWI Payment Form integration without API

For merchants, this is the way to integrate without API methods implementation.

Invoice parameters are included into the Payment Form URL — see examples and parameters list below. When the form is opened, the customer is automatically billed for the order.

When paying an invoice issued this way the payment is authorized without the participation of the merchant. As the two-step payment scheme is used (authorization and confirmation), you need to confirm payment in your Account Profile. By default, the service waits for the payment confirmation in 72 hours. When time is up the payment is confirmed automatically.

GET →

Link to the form with payment amount

https://oplata.qiwi.com/create?publicKey=5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]=Order_123&extras[cf3]=winnie@pooh.ru&readonly_extras=cf1&comment=some%20comment&amount=100.00

Link to the form without payment amount (it is filled in by the customer)

https://oplata.qiwi.com/create?publicKey=5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3ceEvMvCq55ToeErzhvK6rVkQLaCrYUQcYF5QkS8nCrjnPsLQgsLxqrpQgJ7hg2ZHmEHXFjaG8qjvgcep&extras[cf1]=Order_123&extras[cf3]=winnie@pooh.ru&readonly_extras=cf1
Parameter Description Type Required
publicKey Merchant identification key. For each siteId the unique key is produced. You can get the key in your Account Profile in Settings section. String +
billId Unique invoice identifier in the merchant's system. It must be generated on your side with any means. Arbitrary sequence of digits and letters, _ and - symbols as well. If not used, on 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) -
currency Currency code for the purchase. Possible values: RUB, EUR, USD. Default value RUB String(3) -
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 a customer return to the merchant site after the successful payment. URL should be UTF-8 encoded. URL-encoded string -
paymentMethod Payment method suggested to the customer on the QIWI form. Possible values: CARD, SBP, QIWI_WALLET. If the method is not enabled for the merchant, an available method is suggested. By default, CARD. 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 -
extras[themeCode] Extra field with code style of the Payment form URL-encoded string -
readonly_extras List of the extra fields which customer cannot edit on the invoice pay form String, separator of the field names ,. Example: cf1,cf3 -

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

API invoice issue and QIWI payment form

Invoice creation when payment is put 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
   },
   "billPaymentMethodsType": [
      "QIWI_WALLET",
      "SBP"
   ],
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customFields": {}
}

Notification with paymentId

  "payment": {
    "type": "PAYMENT",
    "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",  <== paymentId necessary for confirmation
    "createdDateTime": "2022-07-27T12:43:35+03:00",
    "status": {
        "value": "SUCCESS",
        "changedDateTime": "2022-07-27T12:43:47+03:00"
    },
    "amount": {
        "value": 1.00,
        "currency": "RUB"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "512391******6871",
        "cardHolder": null,
        "cardExpireDate": "3/2030"
    },
    "tokenData": {
        "paymentToken": "cc123da5-2fdd-4685-912e-8671597948a3",
        "expiredDate": "2030-03-01T00:00:00+03:00"
    },
    "customFields": {
        "cf2": "dva",
        "cf1": "1",
        "cf4": "4",
        "cf3": "tri",
        "cf5": "5",
        "full_name": "full_name",
        "phone": "phone",
        "contract_id": "contract_id",
        "comment": "test",
        "booking_number": "booking_number"
    },
    "paymentCardInfo": {
        "issuingCountry": "643",
        "issuingBank": "Тинькофф банк",
        "paymentSystem": "MASTERCARD",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
    },
    "customer": {
        "email": "darta@mail.ru",
        "account": "11235813",
        "phone": "79850223243"
    },
    "gatewayData": {
        "type": "ACQUIRING",
        "eci": "2",
        "authCode": "0123342",
        "rrn": "001239598011"
    },
    "billId": "191616216126154",
    "flags": [
        "AFT"
    ]
  },
  "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

Invoice creation when payment is processed 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"
    ]
}

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.

In two-step payment scenario:

  1. Create an invoice using the API request Invoice with parameters:

    • The API access key.
    • The amount of the invoice (amount).
    • The date before which the invoice must be paid (expirationDateTime).
    • (optional) Other invoice data:
      • Customer data (customer, address).
      • Comment on the invoice (comment).
      • Other information (customFields).

    To limit payment methods accessible for the customer on the Payment form, specify them in billPaymentMethodsType API parameter. Listed methods should be enabled for siteId of the API request.

  2. Redirect the customer to QIWI Payment form using URL from payUrl parameter of the API response, or use Popup JavaScript library to open the form in a popup window.
  3. Get paymentId identifier of the payment:
  4. Send API request Payment confirmation with received paymentId identifier.
  5. Wait for the payment confirmation. Either you receive a notification, or send Capture status API request in cycle to get an information about the capture.

The reimbursement is formed only after the payment confirmation.

In one-step payment scenario:

  1. Create an invoice using the API request Invoice with parameters:

    • The API access key.
    • The amount of the invoice (amount).
    • The date before which the invoice must be paid (expirationDateTime).
    • The flag for one-step scenario "flags":["SALE"].
    • (optional) Other invoice data:
      • Customer data (customer, address).
      • Comment on the invoice (comment).
      • Other information (customFields).

    To limit payment methods accessible for the customer on the Payment form, specify them in billPaymentMethodsType API parameter. Listed mods should be enabled for siteId of the API request.

  2. Redirect the customer to QIWI Payment form using URL from payUrl parameter of the API response, or use Popup JavaScript library to open the form in a popup window.
  3. Wait for the payment completion. Either you receive a notification, or send Invoice status API request in cycle to get an information about the 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"
   }
   }
}

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 manager in QIWI Support to enable that.

See details of 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:

Then redirect the customer to QIWI Payment form using URL from payUrl parameter of the API response, or use Popup JavaScript library to open the form in a popup window. If one or more payment tokens have been issued for the customer, the Payment form would display their linked cards.

qiwi-form-tokens

To use the payment token, the customer chooses a card from the drop-down list. Card data or 3-D Secure authentication is not required.

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 merchant's payment form.

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 in API, the URL of the QIWI Form is taken from payUrl field of the API response.

Example of the URL with successUrl parameter

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

You can add the following parameter to the URL:

Parameter Description Type
successUrl URL for a customer return to the merchant site after the successful payment. Redirect proceeds after the successful 3DS authentication. URL should be UTF-8 encoded. URL-encoded string
lang Interface language of the QIWI form. By default, ru ru, eng
paymentMethod Payment method suggested to the customer on the QIWI form. If the method is not enabled for the merchant, some available method is suggested. By default, CARD. CARD, SBP, QIWI_WALLET

Example of event listener for iframe

window.addEventListener('message', function (event) {
    switch (event.data) {
        case 'INITIALIZED':
            // Form loaded
            break;
        case 'PAYMENT_ATTEMPT':
            // Payment attempt
            break;
        case 'PAYMENT_SUCCEEDED':
            // Payment successful
            break;
        case 'PAYMENT_FAILED':
            // Payment failed
            break;
    }
}, false)

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

When opening URL of the QIWI Form in <iframe>, use additional parameter allow:

<iframe allow="payment" src="<ссылка payUrl> ..." />

You can use postMessage method to listen events in the Form.

Possible values of the Form state:

The library helps to use QIWI Payment Form in a popup. It has two methods:

To install the library, add the following script into your web-page:

<script src='https://oplata.qiwi.com/popup/v2.js'></script>

Create invoice

Create new invoice

params = {
    publicKey: '5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3c******',
    amount: 10.00,
    phone: '79123456789',
    email: 'test@example.com',
    account: 'account1',
    comment: 'Payment',
    customFields: {
        data: 'data'
    },
    lifetime: '2022-04-04T1540'
}

QiwiCheckout.createInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })

To create invoice and open its payment form in a popup, call method QiwiCheckout.createInvoice. Method has the following parameters:

Parameter Description Format
publicKey Required. Merchant identification key. For each siteId the unique key is produced. You can get the key in your Account Profile in Settings section. String
amount Required. Amount of the invoice rounded down on two decimals Number(6.2)
phone Phone number of the client to which the invoice is issuing (international format) String
email E-mail of the client where the invoice payment link will be sent String
account Client identifier in merchant’s system String
comment Invoice commentary String(255)
customFields Additional invoice data. Obtain full list of data fields in the description of the same parameter in invoice API request Object
lifetime Invoice payment’s due date. If the invoice is not paid before that date, it assigns final status and becomes void URL-encoded string YYYY-MM-DDThhmm

Open invoice

Open an existing invoice in popup

params = {
    payUrl: '<URL of the invoice Pay form>'
}

QiwiCheckout.openInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })

To open existing invoice payment form in a popup, call method QiwiCheckout.openInvoice. Method has single parameter:

Parameter Description Type Required
payUrl Required. URL of the invoice Pay form String +

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 and provide the following information:

Some optional data are also used:

To use your Custom Payment form:

Example of the customized Payment form:

Customer form

Payment Through Merchant Web Form

When you integrate payments with 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:API: Payment request
One-step payment — all payment methods
Two-step payment — only cards activate qb qb->>store:Operation status, 3DS data or
QR code for Faster Payment System rect rgb(255, 238, 223) 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:API: Completing customer authentication request end qb->>ips:Request for charging funds activate ips ips->>qb:Operation status qb->>store:Notification on the status of the operation store->>qb: Check operation status
API: Payment status request qb->>store: Operation status rect rgb(255, 238, 223) Note over store, ips:Two-step payment store->>qb:API: Payment confirmation request qb->>ips:Confirming card charging deactivate ips qb->>store:Notification on the payment confirmation store->>qb: Check operation status
API: Payment confirmation status request qb->>store: Operation status end deactivate qb deactivate store

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

Bank card payment

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.

Awaiting 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, proceed with 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 authentication 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 customer 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 manager in QIWI Support 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.

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 manager in QIWI Support.

Receiving QR code

Example of request for SBP payment

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
      "mediaType": "image/png",
      "width": 300,
      "height": 300
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com"
}

Example of response with QR code

{
  "qrCodeUid": "Test12",
  "amount": {
    "currency": "RUB",
    "value": "100.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "CREATED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

When paying with Faster Payment System a customer scans a QR code and receives a payment link to open and make payment in her bank application.

To create a QR code for the payment, send the API request Faster Payment System QR code with specific parameters:

In the response, the JSON object qrCode contains the data of the QR code:

SBP payment status

When payment status becomes final, the notification will be sent with the corresponding QR code API request identifier in qrCodeUid field. Payment status can be determined with paymentId identifier from the same notification by the API request.

QR code status

Example of response for SBP QR code status request

{
  "qrCodeUid": "Test",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "PAYED"
  },
  "payment": {
    "paymentUid": "A22231710446971300200933E625FCB3",
    "paymentStatus": "COMPLETED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

To get QR code information you can use the Faster Payment System QR Code Status API request. Response contains QR code details including its current status so you can check if it is still a valid one.

Payment from mobile phone account

Purchases from a mobile phone account occur without entering card data. After merchant initiates payment, customer receives SMS from their mobile network operator. SMS contains the information about corresponding purchase. Customer approves or rejects the payment by the response SMS.

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

How to send a payment

Payment example

{
  "paymentMethod": {
    "type": "MOBILE_COMMERCE",
    "phone": "+79111111111"
  },
  "amount": {
    "value": 5900.00,
    "currency": "RUB"
  },
  "flags": [
    "SALE"
  ],
  "customer": {
    "account": "79111111111",
    "email": "test@qiwi.com",
    "phone": "79111111111"
  }
}

When sending payment, put into paymentMethod object in Payment API request the following data:

Server Notifications

Notification example

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-Type: application/json
Signature: j4wnfnzd***v5mv2w=
Host: example.com
{
   "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":"124",
         "authCode":"181211"
      },
      "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 Account Profile in Settings section.

To put different notification address for a separate operation, use the following parameters in the 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 must be converted to UTF-8 encoded string representation.

    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, secret, parameters)

    where:

    • secret – HMAC hash key. It is the server notification key in Settings section of the Merchant Account Profile.
    • 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

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: example.com
{
  "payment": {
    "paymentId": "A22170834426031500000733E625FCB3",
    "customFields": {},
    "type": "PAYMENT",
    "createdDateTime": "2022-08-05T11:34:42+03:00",
    "status": {
      "value": "SUCCESS",
      "changedDateTime": "2022-08-05T11:34:44+03:00"
    },
    "amount": {
      "value": 5,
      "currency": "RUB"
    },
    "paymentMethod": {
      "type": "SBP",
      "phone": "79111112233"
    },
    "customer": {
      "phone": "0",
      "bankAccountNumber": "4081710809561219555",
      "bic": "044525974",
      "lastName": "ИВАНОВ",
      "firstName": "ИВАН",
      "middleName": "ИВАНОВИЧ",
      "simpleAddress": ""
    },
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": [
      "SALE"
    ]
  },
  "type": "PAYMENT",
  "version": "1"
}
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
billId Corresponding invoice ID for the operation String(200) Always
qrCodeUid QR-code issue operation identifier in RSP's system String In case of operation with Faster Payment System
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
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) In case of operation rejection
reasonMessage Rejection reason description String(200) In case of operation rejection
errorCode Error code Number In case of error
paymentMethod Payment method data Object Always
type Payment method type: CARD — bank card, TOKEN — payment token, SBP — Fast Payments System, QIWI_WALLET — QIWI Wallet balance String Always
paymentToken Card payment token String When payment token is used for the payment
maskedPan Masked card PAN String When card or payment token is used for the payment
rrn Payment RRN (ISO 8583) Number When card or payment token is used for the payment
authCode Payment Auth code Number When card or payment token is used for the payment
phone Phone number linked to the customer's card, or QIWI Wallet number String When paying through Fast Payments System, or from QIWI Wallet balance
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
bankAccountNumber Payer's bank account number String When paying through Fast Payments System
bic Issuer BIC String When paying through Fast Payments System
lastName Customer's last name String When paying through Fast Payments System
firstName Customer's first name String When paying through Fast Payments System
middleName Customer's middle name String When paying through Fast Payments System
simpleAddress Customer's address String When paying through Fast Payments System
inn Customer's TIN String When paying through Fast Payments System
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
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)
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) In case of operation rejection
reasonMessage Rejection reason description String(200) In case of operation rejection
errorCode Error code Number In case of error
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
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, contact your manager in QIWI Support and request access to the solution.

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": "My сomment",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "value": 2.00,
                "currency": "RUB"
            },
            "orderId": "dressesforwhite",
            "comment": "Some purchase 1"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "value": 1.00,
                "currency": "RUB"
            },
            "orderId": "shoesforvalya",
            "comment": "Some purchase 2"
        }
    ]
}
'

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": "My с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": "Some purchase 1"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "1.00"
            },
            "orderId": "shoesforvalya",
            "comment": "Some purchase 2"
        }
    ]
}

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"
  },
  {
    "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": "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"
       }
    ]
}

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 authorization of the card 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": "Some goods"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "Flowers"
  }
  ]
}

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": "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"
        }
    ]
}

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": "My с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": "Purchase 1"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Purchase 2"
            }
        ]
    },
    "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": "Some purchase"
            },
            {
                "type": "MERCHANT_DETAILS",
                "siteUid": "Obuc-01",
                "splitAmount": {
                    "value": 1,
                    "currency": "RUB"
                },
                "splitCommissions": {
                    "merchantCms": {
                        "value": 0.02,
                        "currency": "RUB"
                    },
                    "userCms": null
                },
                "orderId": "shoesforvalya",
                "comment": "Some purchase 2"
            }
        ]
    },
    "type": "REFUND",
    "version": "1"
}

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

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 manager in QIWI Support to enable that.

If merchant's service uses QIWI Payment Form, contact your manager in QIWI Support to enable displaying list of cards linked to the payment tokens. Otherwise a customer may not use linked cards on the Form. A list of cards is displayed for payments from the same site for which the tokens are issued.

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, you may use one of the following methods:

  1. Without payment (preferred method). Use API request Card verification or Invoice issuing. Include the following extra parameters:
    • account field with a unique customer ID in the RSP system:
    • "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"] field, in case of Invoice issuing request.

    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:

    You can always request a card verification status — in the response you will receive a createdToken object with payment token details.

    See Customer Card Verification section for details.

  2. During payment process. Include additional options in the API request Payment or Invoice, depending on which API you use:
    • "flags": ["BIND_PAYMENT_TOKEN"] is a flag for issuing a payment token.
    • customer.account is 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:

    • In the synchronous response to the payment request in the createdToken field.
    • In the PAYMENT notification after payment is completed successfully, in the tokenData field.

QIWI Wallet payment token issue

Example of a request with QIWI Wallet payment token issue initiation

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

{
   "requestId": "asd1232q77w1e3212",
   "phone": "79022222222",
   "accountId": "token324"
}

Response

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

Example of a request with providing QIWI Wallet payment token

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

{
   "requestId": "asd1232q77w1e3212",
   "smsCode": "1223"
}

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:

    /payin-tokenization-api/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:

    /payin-tokenization-api/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.

Customer Card Verification

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 manager in QIWI Support 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 token generation, set customer.account parameter with unique customer identifier in the merchant's system. Do not specify invoice amount in the request. Extract billId parameter from the response — it is used on step 4.
  2. Redirect customer to the Payment Form — reference URL taken from payUrl field of the response.
  3. On the Payment Form, customer provides card details and submits it for verification. On the form, 3-D Secure authentication performs for customer. check card
  4. When card verification finishes, you get CHECK_CARD notification with the result, or you can request current status of the verification — put there billId identifier from step 2 as a unique identifier of the card verification. Result includes:

    • information about whether card is accessible for purchases in isValidCard field (true — card number is valid and card can be purchased);
    • payment token data in createdToken field.

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 authentication

{
    "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" API request. Put in the request:
    • Unique verification identifier (requestUid field in the request URL).
    • Card data (cardData in the request body). Required parameters — PAN, card expiration date, and CVV2.

    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 authentication in the card verification service. Contact QIWI Support to enable or disable 3-D Secure (3DS) procedure. If 3DS is enabled, you receive "requirements" object 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 authentication 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.

When verification finishes, you get CHECK_CARD notification with the result, or you can always get current card verification status by API request.

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 merchant'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 manager in QIWI Support.

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
DECLINED PAYMENT Request for authorization 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
DECLINED CAPTURE Request for payment confirmation is rejected API response to the status request
SUCCESS PAYMENT Request for authorization is successfully processed Notifications
COMPLETED PAYMENT Request for authorization 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
INVALID_RECEIVER_DATA Error on transmitting receiver data
DECLINED_BY_MPI Rejected by MPI
DECLINED_BY_FRAUD Rejected by fraud monitoring
REATTEMPT_NOT_PERMITTED Repeated authorization request forbidden due to obtained response from a Payment system
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 authorization
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
PAYMENT_EXPIRED_3DS 3-D Secure authentication not passed
QW_LIMIT_ERROR Exceeded limits for QIWI Wallet (monthly, daily, etc)
QW_IDENTIFICATION_ERROR QIWI Wallet identification required or identification level is not enough for the customer
QW_AUTH_ERROR The current authentication level does not match the required
QW_INSUFFICIENT_FUNDS Insufficient funds
QW_AMOUNT_ERROR Forbidden payment amount in QIWI Wallet (amount is less than the minimum allowed amount or larger than the maximum allowed amount, or daily limit exceeded or zero amount)
QW_REGISTRATION_ERROR QIWI Wallet registration error
QW_AGENT_ERROR QIWI Wallet agent is blocked
QW_ACCOUNT_ERROR QIWI Wallet account is blocked
QW_IDENTIFICATION_STATUS_ERROR Attempt to transfer limited amount in another currency in QIWI Wallet
QW_CURRENCY_ERROR Currency error in QIWI Wallet (currency not found, wallet with that currency is not found)
QW_PAYMENT_ERROR QIWI Wallet payment error
QW_PROVIDER_ERROR QIWI Wallet provider is blocked
QW_SMS_CONFIRM_EXPIRED SMS code is expired in QIWI Wallet

API Method Reference

Invoice

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "billPaymentMethodsType": [
      "QIWI_WALLET",
      "SBP"
   ],
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {
    "cf1": "Some data"
   }
}
{
    "siteId": "23044",
    "billId": "893794793973",
    "invoiceUid": "d875277b-6f0f-445d-8a83-f62c7c07be77",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "CREATED",
      "changedDateTime": "2018-03-05T11:27:41"
    },
    "comment": "Text comment",
    "customFields": {
      "cf1": "Some data"
    },
    "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

GET /partner/payin/v1/sites/site-01/bills/d35cf63943e54f50badc75f49a5aac7c/details HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
{
  "billId": "d35cf63943e54f50badc75f49a5aac7c",
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "status": {
    "value": "PAID",
    "changedDateTime": "2022-03-05T11:27:41"
  },
  "comment": "Text comment",
  "customFields": {
    "cf1": "Some data"
  },
  "expirationDateTime": "2022-04-13T14:30:00",
  "payUrl": "https://oplata.qiwi.com/form/invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77",
  "payments": [
    {
        "siteId": "site-01",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2022-03-05T11:23:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 100.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 100.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "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": "DECLINED",
            "changedDateTime": "2022-03-05T11:23:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "cf1": "1",
            "cf2": "0"
        }
    },
    {
        "siteId": "site-01",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2022-03-05T11:26:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 100.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 100.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "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": "2022-03-05T11:34:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    }
]
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

List of payments on the invoice

GET /partner/payin/v1/sites/site-01/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
[
  {
    "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",
    "billId": "191616216126154",
    "createdDateTime": "2022-07-27T12:43:35+03:00",
    "amount": {
        "currency": "RUB",
        "value": "1.00"
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": "0.00"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "561251******6871",
        "rrn": "002612398011",
        "authCode": "067842"
    },
    "createdToken": {
        "token": "cc2451a5-2fdd-4685-912e-8671597948a3",
        "name": "561251******6871",
        "expiredDate": "2030-03-01T00:00:00+03:00"
    },
    "customer": {
        "account": "11235813",
        "email": "darta@mail.ru",
        "phone": "79850223243"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2022-07-27T12:43:47+03:00"
    },
    "callbackUrl": "https://qiwi.com",
    "comment": "test",
    "customFields": {
        "customer_email": "darta@mail.ru",
        "customer_account": "11235813",
        "customer_phone": "79850223243",
        "cf1": "1",
        "cf2": "dva",
        "cf3": "tri",
        "cf4": "4",
        "cf5": "5",
        "BIND_PAYMENT_TOKEN": "true",
        "themeCode": "customization_OK",
    },
    "paymentCardInfo": {
        "issuingCountry": "643",
        "issuingBank": "Тинькофф банк",
        "paymentSystem": "MASTERCARD",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "TNW|TNW|Mastercard® NewWorld—ImmediateDebit|TNW|Mastercard New World-ImmediateDebit"
    }
  }
]
{
  "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

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

{
  "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"
  },
  "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"
  },
  "flags" : [ ]
}
{
  "serviceName":"payin-core",
  "errorCode":"validation.error",
  "description":"Validation error",
  "userMessage":"Validation error",
  "dateTime":"2022-11-13T16:49:59.166+03:00",
  "traceId":"fd0e2a08c63ace83",
  "cause":{
    "paymentToken": [
      "Exchange token error. Token disabled, please create new one"
    ]
  }
}
{
  "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

GET /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" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049",
    "rrn": "124",
    "authCode": "182817",
  },
  "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":"2022-11-13T16:49:59.166+03:00",
  "traceId":"fd0e2a08c63ace83",
  "cause":{
    "paymentToken": [
      "Exchange token error. Token disabled, please create new one"
    ]
  }
}
{
  "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 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...."
  }
}
{
  "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

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

{
  "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

GET /partner/payin/v1/sites/test-01/payments/1811/captures/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
{
  "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"
}

Faster Payment System QR Code

PUT Method

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

{
  "amount": {
    "value": 1.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 60,
    "image": {
      "mediaType": "image/png",
      "width": 300,
      "height": 300
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://example.com"
}
{
  "qrCodeUid": "Test12",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 60,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "CREATED"
  },
  "createdOn": "2022-08-11T20:10:32+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":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

POST Methods

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

{
  "qrCodeUid": "Test12",
  "amount": {
    "value": 1.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 60,
    "image": {
      "mediaType": "image/png",
      "width": 300,
      "height": 300
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://example.com"
}
{
  "qrCodeUid": "Test12",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 60,
    "image": {
      "mediaType": "image/png",
      "width": 300,
      "height": 300,
      "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQD?type=02&bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "CREATED"
  },
  "createdOn": "2022-08-11T20:10:32+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":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Faster Payment System QR Code Status

GET /partner/payin/v1/sites/test-01/sbp/qrCodes/Test HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
{
  "qrCodeUid": "Test",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 60,
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "PAYED"
  },
  "payment": {
    "paymentUid": "A22231710446971300200933E625FCB3",
    "paymentStatus": "COMPLETED"
  },
  "createdOn": "2022-08-11T20:10:32+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":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}

Refund

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

{
  "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

GET /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
{
  "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

GET /partner/payin/v1/sites/test-01/payments/1811/refunds HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
[
 {
  "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 decline

POST /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132/decline HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com
{
  "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"
}

Card verification status

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
{
    "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 receipt is passed on to the JSON-object cheque of invoice and payment operation API requests.

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

For the 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 - Outgoing cash
CONSUME_RETURN - Outgoing 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.