Overview

Doc version 1.22 | 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:

• Debit or credit cards, like Visa, Mastercard, and Mir.
• QIWI Wallet.
• Faster Payments Systems (SBP).
• Mobile phone account.

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:

• Payment through QIWI Form.
• Payment through merchant form.

Available Payment Methods

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

** — PCI DSS certification is required.

*** — by issuing a payment token for QIWI wallet

Operation Types

The following operations are available in the protocol:

• An Invoice — an electronic document that the merchant has issued to the customer. Contains information about the amount and number of the customer order. It is not a financial entity and has a limited lifespan. Billing is required to obtain a URL to the QIWI payment form.
• Payment — a cash write-off transaction from the customer in favour of the merchant. The actual write-off occurs only after confirmation (see Capture). When working through the QIWI payment form, Payment is an attempt to pay the bill (see Invoice).
• Complete — the completion of 3DS verification of the customer. It is used when working through the Merchant Payment Form.
• Confirmation (Capture) — confirmation of authorization (charging) of the funds. Only single successful payment confirmation is possible.
• Refund — refund to the customer on a successful payment. Financial operation of debiting money from the merchant in favor of the customer. If there was no confirmation for Payment operation, you will receive the Reversal flag in the response to Refund operation request and the money from the customer's account will not be transferred to the Merchant's account (the acquiring fee is also not withheld).

Payment processing and settlements scheme

Interaction format

The Payment protocol API is built on the REST architecture, where data and methods are considered as resources accessed via calling Uniform Resource Identifiers (URIs).

API uses HTTPS-requests for calling its methods. API endpoint has URL:

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

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

It is necessary to put Accept: application/json header into the request headers as API always responds in JSON format.

The API methods provide logical idempotence, i. e. repeating a method multiple times is equivalent to doing it once. However, the response may change (for example, the state of an invoice may change between requests).

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>

How to Test Operations

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.

You don't need to re-release the API access key when you go into the 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

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

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

You can also check payment token issue. Issue scheme in the test mode is the same as in production mode. It is described in Card payment token issue section.

Test card numbers

• Mir: 2200000000000004, 2200000000000012, 2200000000000020, 2200000000000038, 2200000000000046, 2200000000000053, 2200000000000061, 2200000000000079, 2200000000000087, 2200000000000095, 2200000000000103, 2200000000000111
• Visa: 4256000000000003, 4256000000000011, 4256000000000029, 4256000000000037, 4256000000000045, 4256000000000052, 4256000000000060, 4256000000000078, 4256000000000086, 4256000000000094, 4256000000000102, 4256000000000110
• Mastercard: 5236000000000005, 5236000000000013, 5236000000000021, 5236000000000039, 5236000000000047, 5236000000000054, 5236000000000062, 5236000000000088, 5236000000000096, 5236000000000104, 5236000000000112, 5236000000000120
• UnionPay: 6056000000000000, 6056000000000018, 6056000000000026, 6056000000000034, 6056000000000042, 6056000000000059, 6056000000000067, 6056000000000075, 6056000000000083, 6056000000000091, 6056000000000109, 6056000000000117

Test 3-D Secure operations

1. Create a payment link via API, or without it.
2. Use any card from Test Card Numbers list.
3. For 3-D Secure in test mode CVV should be 849 or use a cardholder name that contains the string 3ds.
4. Confirm or reject the transaction on the form.

Test limits

• You may use only Russian ruble (643 code) for the currency (amount.currency).

• Restrictions on the amount and number of operations:

  • Maximum allowed amount of a single transaction is 10 rubles.
  • Maximum number of transactions is 100 per day. All transactions within the current day (by Moscow timezone) with each transaction' amount not more than 10 rubles are taken into account.

Payment through Faster Payments System

In test mode, you can use only QR-code issue and its status request. To test various responses, use different payment amounts (amount.value field):

• 200 — QR-code is successfully created.
• For any other amounts the payment would be unsuccessful with DECLINED status.

When requesting FPS payment status in the test mode the following statuses are returned:

• CREATED — Payment created.
• DECLINED — Payment declined.
• EXPIRED — Payment QR-code lifetime is expired.

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:

• Card payment token.
• Faster Payments System.
• QIWI Wallet.

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

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

• URL https://oplata.qiwi.com/create?publicKey={key}&{parameter}={value}

• Parameters

  Invoice parameters put to the URL query.

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": "Tinkoff Bank",
        "paymentSystem": "MASTERCARD",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
    },
    "merchantSiteUid": "test-00",  
    "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/captures/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:
   • From server notification after successful holding of funds.
   • From the response to the Invoice payments list request.
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:

• API access key.
• Amount of the invoice (amount).
• Last date of payment for the invoice (expirationDateTime).
• Customer identifier for which the payment token was issued, in customer.account parameter. Payment by payment token is not possible without this parameter.
• Other information about the invoice (comment, customFields).

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.

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:

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 link> ..." />

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

Possible values of the Form state:

• INITIALIZED — Form loaded.
• PAYMENT_ATTEMPT — Payment attempt was performed.
• PAYMENT_SUCCEEDED — Payment successfully processed.
• PAYMENT_FAILED — Payment failed.
• INITIALIZATION_FAILED — Error on the Form loading.

Checkout Popup Library

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

• Create a new invoice.
• Open an existing invoice.

Demo popup

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:

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:

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:

• Unique alias for the Payment form (latin letters, digits, and - dash symbol).
• Merchant name to be displayed on the Form.
• Logo in PNG or SVG format with 48x48 size or proportionally larger.
• Color of buttons, in HEX.

Some optional data are also used:

• Offer reference.

To use your Custom Payment form:

• Send the alias for the Payment form in "themeCode" field of customFields object of API request Invoice:

  "themeCode":"merchant01-theme01".

  URL received in payUrl field of the API response points to the Custom Payment form.

• Send the alias for the Payment form in direct call of the form in extras[themeCode] parameter:

  ...&extras[themeCode]=merchant01-theme01.

Example of the customized Payment form:

Payment Through Merchant Web Form

Bank Card payment method is available for integration by default. The following payment methods are enabled on demand:

• Card and QIWI Wallet payment token.
• Faster Payments System.
• Mobile phone account.

Payment process

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

• API access key;
• amount of payment;
• payment method;
• other information for payment creation.

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 funds 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 client charging (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 client card (two-step payment), send the following data in API request Payment:

• API access key;
• payment amount data;
• payment method parameters in paymentMethod object:
  • type — CARD;
  • pan — card number;
  • expiryDate – card expiry date in MM/YY format;
  • cvv2 — card CVV2/CVC2;
  • holderName – card holder name (Latin letters);
• other information about the payment.

When the customer card was previously tokenized on your side, the following parameters in paymentMethod should be included:

• cardTokenPaymentType – parameter for correct processing of transactions in the payment systems. Allowed values:
  • FIRST_PAYMENT — when you are going to save the card data on your side;
  • INITIATED_BY_CLIENT — transaction on the saved card initiated by a client;
  • INITIATED_BY_MERCHANT — transaction on the saved card initiated by the merchant;
  • RECURRING_PAYMENT — recurring operation on the saved card;
  • INSTALLMENT — repeated operation on the saved card in accordance with payment schedule for credit repayment.
• firstTransaction – JSON-object with transaction identifier info where card was saved. Contains fields:
  • paymentId – unique payment identifier in RSP information system;
  • trnId – unique payment identifier in NSPK information system.

For the two-step payment (default option), the reimbursement is formed only after the order confirmation.

To make one-step payment without the funds holding, include the "flags":["SALE"] parameter in the API request Payment. If you do not pass this parameter, the funds holding for the payment is made and service waits for confirmation of the payment.

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 3-D Secure authentication of the customer, the payment response contains the requirements.threeDS JSON-object with fields:

• acsUrl — 3-D Secure authentication server URL to redirect to the issuer's confirmation page;
• pareq — an encrypted 3-D Secure authentication request.

To proceed with additional authentication from the issuer, send a POST form to the 3-D Secure authentication server URL with parameters:

• TermUrl — customer redirection URL after successful 3-D Secure authentication;
• MD — a unique transaction identifier;
• PaReq — the pareq value from the response to the payment request.

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:

• unique RSP ID;
• payment number (paymentId option) from the response to the payment request;
• 3-D Secure verification value (PaRes value)

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"
    },
    "merchantSiteUid":"test-00",
    "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/captures/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:

• Get paymentId of the payment:
  • From notification after successful holding funds.
  • From the response to Payment status API request.
• Send API request Confirm payment with received paymentId value.

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.

When using payment token for the payment, customer does not have to enter its card data and proceed with 3-D Secure authentication.

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

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

• API access key;
• payment amount data;
• payment method parameters in paymentMethod object:
  • type – TOKEN;
  • paymentToken – payment token string;
• customer identifier in the RSP system for which the payment token was issued, in customer.account parameter (without this parameter, you cannot pay with the payment token.);
• other information about the payment.

When the customer card was previously tokenized on your side, the following parameters in paymentMethod should be included:

• cardTokenPaymentType – parameter for correct processing of transactions in the payment systems. Allowed values:
  • INITIATED_BY_CLIENT — transaction on the saved card initiated by a client;
  • INITIATED_BY_MERCHANT — transaction on the saved card initiated by the merchant;
  • RECURRING_PAYMENT — recurring operation on the saved card;
  • INSTALLMENT — repeated operation on the saved card in accordance with payment schedule for credit repayment.
• firstTransaction – JSON-object with transaction identifier info where card was saved. Contains fields:
  • paymentId – unique payment identifier in RSP information system;
  • trnId – unique payment identifier in NSPK information system.

Faster Payments System

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

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

Receiving QR code

Example of request for FPS 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:

• Unique QR code API request identifier.
• qrCode object with QR code parameters:
  • qrCode.type— DYNAMIC.
  • qrCode.ttl — code lifetime (minutes). The QR code is deactivated after the period ends. Default value is 72 hours.
  • qrCode.image — QR code image size and type.
• amount — payment amount.
• paymentPurpose — payment details. If it is empty customer bank app displays merchant's store title.

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

• image.content — base64-encoded QR code. After decryption, you get an image to show to the customer.
• payload — URL-based QR for customer redirection to its bank app.

FPS 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 FPS 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.

FPS token payment

Request body for payment with FPS token

{
  "tokenizationAccount": "customer123",
  "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6"
}

See details about FPS payment token issue in this section.

Use Payment by FPS token API method with the following parameters:

• token — FPS payment token;
• tokenizationAccount — client identifier for which the token was issued.

Testing operations

See information in this section.

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:

• type — MOBILE_COMMERCE.
• phone — phone number, from which to make a payment. Number should be in international format with + sign.

Server Notifications

Notification

POST <callback-path> HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: <callback-url>

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

• PAYMENT — sends when a payment operation is made;
• CAPTURE — sends when a payment confirmation is made;
• REFUND — sends when a refund for payment is made;
• CHECK_CARD — sends when a card verification is made;
• TOKEN — sends when a Faster Payments System payment token is issued and applied for payment operations.

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:

• callbackUrl — in the Payment, Payment confirmation, Refund API requests.
• customFields.invoice_callback_url — in the Invoice API request.

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:

• 79.142.16.0/20
• 195.189.100.0/22
• 91.232.230.0/23
• 91.213.51.0/24

To treat notification as successfully delivered, we need your notification server to respond with HTTP code 200 OK.

Notification Authorization

Notification headers example

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

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
   • TOKEN type: token.merchantSiteUid|token.account|token.status.value|token.status.changedDateTime

2. Calculate hash HMAC value with SHA256 algorithm (signature string and secret key should be UTF8-encoded):

   hash = HMAC(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:

• One attempt on waiting 5 seconds
• One attempt on waiting 1 minutes
• Three attempts on waiting 5 minutes

Resend time may be increased.

PAYMENT Notification Format

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

PAYMENT notification body

{
  "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"
    },
    "merchantSiteUid": "test-00",
    "customer": {
      "phone": "0",
      "bankAccountNumber": "4081710809561219555",
      "bic": "044525974",
      "lastName": "IVANOV",
      "firstName": "IVAN",
      "middleName": "IVANOVICH",
      "simpleAddress": "",
      "bankMemberId": "100000000008"
    },
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": [
      "SALE"
    ]
  },
  "type": "PAYMENT",
  "version": "1"
}

PAYMENT notification body for a split payments

{
    "payment": {
        "paymentId": "134d707d-fec4-4a84-93f3-781b4f8c24ac",
        "customFields": {
            "comment": "My comment"
        },
        "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"
        },
        "merchantSiteUid": "test-00",
        "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"
}

CAPTURE Notification Format

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

CAPTURE notification body

{
  "capture": {
    "paymentId": "A22170834426031500000733E625FCB3",
    "captureId": "B33180934426031511100733DG332XTQ1",
    "customFields": {},
    "type": "CAPTURE",
    "createdDateTime": "2022-08-06T11:34:42+03:00",
    "status": {
      "value": "SUCCESS",
      "changedDateTime": "2022-08-06T12:55:44+03:00"
    },
    "amount": {
      "value": 5,
      "currency": "RUB"
    },
    "paymentMethod": {
      "type": "CARD",
      "maskedPan": "54************47",
      "cardHolder": null,
      "cardExpireDate": "12/2024"
    },
    "merchantSiteUid": "test-00",
    "customer": {},
    "billId": "autogenerated-6cd20922-b1d0-4e67-ba61-e2b7310c4006",
    "flags": []
  },
  "type": "CAPTURE",
  "version": "1"
}

REFUND Notification Format

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

REFUND notification body for a split payments refund

{
    "refund": {
        "paymentId": "A22170834426031500000733E625FCB3",
        "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
        },
        "merchantSiteUid": "test-00",
        "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"
}

CHECK_CARD Notification Format

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

CHECK_CARD notification example

{
    "checkPaymentMethod": {
        "status": "SUCCESS",
        "isValidCard": true,
        "threeDsStatus": "PASSED",
        "cardInfo": {
            "issuingCountry": "RUS",
            "issuingBank": "Альфа-банк",
            "paymentSystem": "MASTERCARD",
            "fundingSource": "PREPAID",
            "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
        },
        "createdToken": {
            "token": "7653465767c78-a979-5bae621db96f",
            "name": "54**********47",
            "expiredDate": "2022-12-30T00:00:00+03:00",
            "account": "acc1"
        },
        "requestUid": "uuid1-uuid2-uuid3-uuid4",
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "54************47",
            "cardHolder": null,
            "cardExpireDate": "12/2022"
        },
        "checkOperationDate": "2021-08-16T14:15:07+03:00",
        "merchantSiteUid": "test-00"
    },
    "type": "CHECK_CARD",
    "version": "1"
}

TOKEN Notification format

• HEADERS

  • Signature: XXX
  • Accept: application/json
  • Content-type: application/json

Notification about successful FPS token issue

{
  "token": {
    "status": {
      "value": "CREATED",
      "changedDateTime": "2023-01-01T10:00:00+03:00"
    },
    "merchantSiteUid": "test-00",
    "account": "test",
    "value": "d28a4ff8-548d-4536-927d-fc01123bebbf",
    "expiredDate": "2029-01-01T10:00:00+03:00",
    "tokenizationSource": {
      "type": "QR_CODE",
      "uid": "100220001"
    },
    "bankMemberId": "100000000008"
  },
  "type": "TOKEN",
  "version": "1"
}

Notification on unsuccessful FPS token issue

{
  "token": {
    "status": {
      "value": "REJECTED",
      "changedDateTime": "2023-01-01T10:00:00+03:00"
    },
    "merchantSiteUid": "test-00",
    "account": "test",
    "tokenizationSource": {
      "type": "QR_CODE",
      "uid": "14012000011"
    }
  },
  "type": "TOKEN",
  "version": "1"
}

Refunds and Reversals

Refund and reversal operations are available in the following conditions:

• Refunds are only available for successfully completed payment transactions.
• Reversal of the transaction is possible for two-step payment operations and only for those without received confirm (CAPTURE).

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 comment",
    "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 comment",
    "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:

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

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

Response with split payments

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

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

Refunds on split payments

After a successful authorization of the card charging, a refund is available for the split payment transaction. Both partial and complete refunds are supported.

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 refunds information. Put the total amount of the refund and the refund amount for each split.

JSON-array refundSplits format:

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

Notifications on split payments and refunds

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

• The JSON-array paymentSplits with merchants' payment data is added to the PAYMENT type notification body.
• The JSON-array refundSplits with refund data is added to the REFUND type notification body.

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.

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: * either in tokenizationData object, in case of Card verification request; * or in customer object, in case of Invoice issuing request. * "flags":["CHECK_CARD", "BIND_PAYMENT_TOKEN"] field, in case of Invoice issuing request.

   To secure card data, use different account values for different clients.

   You will receive the card payment token details after complete card verification:

   • In the createdToken field of the final response.
   • In the CHECK_CARD notification.

   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.

   To secure card data, use different account values for different clients.

   You will receive the card payment token details:

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

FPS payment token issue

Request body for the FPS payment token issue

{
  "qrCodeUid": "Test123",
  "qrCode": {
    "type": "TOKEN",
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300
      }
  },
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "tokenizationAccount": "3e2322",
  "flags": ["CREATE_TOKEN"]
}

Response body for the FPS payment token issue

{
  "qrCodeUid": "Test123",
  "qrCode": {
    "type": "TOKEN",
    "ttl": 10,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDб",
    "status": "CREATED"
  },
  "tokenizationPurpose": "Описание с деталями привязки счета",
  "flags": ["CREATE_TOKEN"],
  "token": {
      "status": "CREATED",
      "value": "a4a312345-6789-1234-a567-89a1234567a0",
      "expiredDate": "2023-08-11T10:10:32+03:00"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}