General Information

Edit on GitHub

QIWI PAY service is intended for card payment operations. The service allows RSP to accept secure payments from their clients.

QIWI PAY supports the following operations: payment processing, a two-step payment confirmation, refunds, transaction status query.

Integration Methods

You can use one of the following integration methods on QIWI PAY:

• QIWI PAY WPF — a web payment form on QIWI side. Quick and easy solution for accepting payments with limited functions (only payment transactions).
• QIWI PAY API — fully functional REST-based API for making card payments. All requests are POST-type and the parameters are in JSON body, as well as the responses. RSP implements only the Payment Form Interface.

Service URLs

• To use QIWI PAY WPF, one is required to redirect client to the URL:

https://pay.qiwi.com/paypage/initial.

• To use QIWI PAY API, one is required to send HTTP POST requests to the URL:

https://acquiring.qiwi.com/merchant/direct.

Operations

To indicate which operation is performed, you need to specify Operation code in opcode parameter of each request to API or on loading WPF pay form.

The following operations are accessible through QIWI PAY.

Operation Methods

QIWI PAY Flows

Two payment flows can be used in QIWI PAY:

• One-step — sale operation
• Two-step — auth operation -> capture operation

As a rule, two-step scenario is used when RSP makes verification of service availability after payment is made. Between auth operation and capture operation, RSP can make reversal operation which is not a financial one.

For sale operation, RSP can make reversal but only until the day ends and not for all acquiring banks. Your support manager can provide details.

To make sure you know which operation may be applied, check transaction status and statuses table.

3DS

3DS (3-D Secure) is a common notation for technological frameworks of Visa and MasterCard (Verified By Visa and MasterCard Secure Code, correspondingly). The main goal is to verify the Cardholder's identity by the Issuer before a payment and to prevent card data theft. In practice it work like that. The Cardholder enters his/her card details. The Issuer’s secure web page pops up requesting for verification data (a password or a secret code) to be sent by the Cardholder via SMS. If verification data is valid the payment is processed, if not valid it is rejected.

sale operation via QIWI PAY can be 3DS-validated if the Issuer requires 3DS authentication.

QIWI PAY WPF Payment flow with 3DS verification is explained on the following scheme.

QIWI PAY WPF

RSP only redirects customers to https://pay.qiwi.com/payform. Then customers complete the payment form on QIWI PAY web-site with their card details.

Payment Flow

QIWI PAY WPF one-step payment flow is explained on the following scheme.

Redirect to QIWI PAY WPF

To redirect, use standard web form HTTP POST data request.

<form method="post" action="https://pay.qiwi.com/paypage/initial">
  <input name="opcode" type="hidden" value="1">
  <input name="merchant_site" type="hidden" value="99">
  <input name="currency" type="hidden" value="643">
  <input name="sign" type="hidden" value="bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268">
  <input name="amount" type="text">
  <input type="submit" value="Pay">
</form>

No authorization is required for RSP.

Use the following form fields for payment operations. All fields not specified by the customer should be with hidden type.

QIWI PAY API

Authorization

QIWI PAY API authorizes the request by RSP client certificate validation. Certificate is issued by QIWI for each RSP.

Payment Flow

One-step payment flow

Two-step payment flow

Sale Operation

Request

{
  "opcode": 1,
  "merchant_uid": "10001",
  "merchant_site": 99,
  "pan": "4111111111111111",
  "expiry": "1219",
  "cvv2": "123",
  "amount": 4678.5,
  "currency": 643,
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "ip": "127.0.0.1",
  "email": "merchant@qiwi.com",
  "country": "RUS",
  "city": "Moscow",
  "region": "606008",
  "address": "South Park",
  "phone": "79166554321",
  "user_device_id": "12312321Un43243",
  "user_timedate": "26.08.2016",
  "user_screen_res": 1280,
  "user_agent": "Mozilla FF 312",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "callback_url": "http://domain.tld/callback_service",
  "product_name": "Flowers",
  "receiver_name": "Ivanov, Ivan",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}

All payment operations (sale, auth) use the same set of parameters.

Response for card with no 3DS

{
  "txn_id":172001,
  "txn_status":60,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "card_token_expire": "2018-02-27T21:00:00+00:00",
  "error_code":0,
  "pan": "411111******1111",
  "issuer_name": "QIWI BANK (JSC)",
  "issuer_country": "RUS",
  "amount": 4678.5,
  "currency": 643,
  "auth_code": "2G4923",
  "eci": "05"
}

Response for card with 3DS

{
  "txn_id":172001,
  "txn_status":40,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "acs_url":"https://test.paymentgate.ru/acs/auth/start.do",
  "pareq":"eJxVUmtvgjAUuG79oClYe51uDcsi2B+ZrJPgKtipGHRnUTgy1w5bVwyf4BfjpuJ....."
}

You need to redirect Customer to 3DS standard redirection URL.

Finish 3DS authentication

When Customer returns from 3DS standard redirection URL and completes 3DS authentication successfully, you need to send the following request to finish 3DS authentication process.

Request after successful 3DS authentication

{
  "opcode":2,
  "merchant_site":99,
  "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL",
  "txn_id": "172001"
}

Response to 3DS authentication result

{
  "txn_id":172001,
  "txn_status":60,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "card_token_expire": "2018-02-27T21:00:00+00:00",
  "error_code":0,
  "pan": "411111******1111",
  "issuer_name": "QIWI BANK (JSC)",
  "issuer_country": "RUS",
  "amount": 4678.5,
  "currency": 643,
  "auth_code": "2G4923",
  "eci": "05"
}

Sale Confirmation Operation

Request

{
  "opcode": 5,
  "merchant_site": 99,
  "txn_id": "172001",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}

Response

{
  "txn_id":172001,
  "txn_status":60,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0
}

Cancel Operation

Request

{
  "opcode":6,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}

Response

{
  "txn_id":182001,
  "txn_status":72,
  "txn_type":4,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}

Refund Operation

Request

{
  "opcode":7,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}

Response

{
  "txn_id":182001,
  "txn_status":77,
  "txn_type":3,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}

Payout Operation

Request

{
  "opcode": 20,
  "merchant_uid": "10001",
  "merchant_site": 555,
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "txn_id":182001,
  "amount": "4678.50",
  "currency": 643,
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "callback_url": "http://domain.tld/callback_service",
  "product_name": "Award payment",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e..........................."
}

Response

{
  "txn_id":172001,
  "txn_status":3,
  "txn_type":8,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "pan": "411111******1111",
  "amount": 4678.50,
  "currency": 643,
  "auth_code": "2G4923"
}

Status Query Operation

Request

{
  "opcode":30,
  "merchant_site": 99,
  "order_id": "41324123412342",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}

Response

{
  "transactions": [
    {
      "error_code": 0,
      "txn_id": 3666050,
      "txn_status": 52,
      "txn_type": 2,
      "txn_date": "2017-03-09T17:16:06+00:00",
      "pan": "400000******0002",
      "amount": 10000,
      "currency": 643,
      "auth_code": "181218",
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": "",
      "order_id": "41324123412342"
    },
    {
      "error_code": 0,
      "txn_id": 3684050,
      "txn_status": 72,
      "txn_type": 4,
      "txn_date": "2017-03-09T17:16:09+00:00",
      "pan": "400000******0002",
      "amount": 100,
      "currency": 643,
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": ""
    },
    {
      "error_code": 0,
      "txn_id": 3685050,
      "txn_status": 72,
      "txn_type": 4,
      "txn_date": "2017-03-19T17:16:06+00:00",
      "pan": "400000******0002",
      "amount": 100,
      "currency": 643,
      "merchant_site": 99,
      "card_name": "cardholder name",
      "card_bank": ""
    }
  ],
  "error_code": 0
}

Signature of the Request

public String generateSignature(String data, String secret) {
    try {
        byte[] secretBytes = secret.getBytes("UTF-8");
        Mac hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secretBytes, "HmacSHA256");
        hmac.init(secretKey);
        byte[] signBytes = hmac.doFinal(data.getBytes("UTF-8"));
        return Utils.bytesToHex(signBytes);
    } catch (NoSuchAlgorithmException | UnsupportedEncodingException | InvalidKeyException e) {
        throw new SignatureException("Cannot calculate signature", e);
    }
}

For parameters string amount|currency|merchant_site|opcode

sign = generateSignature("7.00|643|555|3","secret_key");

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

<?php
$hmac = hash_hmac('sha256','7.00|643|555|3','secret_key');
?>

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

user@server:~$ echo -n "7.00|643|555|3" | openssl dgst -sha256  -hmac "secret_key"

(stdin)= 9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

You should sign each operation request. Add the signature in sign parameter for each request.

To calculate signature, use HMAC algorithm with SHA256-hash function. For this, you need secret key parameter obtained with other integration settings.

• Separator is |.
• All values are represented as strings.
• Values are placed alphabetically ordered parameter names, i.e. for parameters { "opcode":1, "merchant_site": 12345, "amount": "15.00", "currency": 643 } string for signature verification is: 15.00|643|12345|1.
• Signed are all the parameters in the request.
• Do not include parameters with empty values.
• Only values are signed, not their names.

Payment Notification

POST /merchant-pay/callback HTTP/1.1
Content-Type: application/json
Host: example.com

{
    "request_id": "d861cxxxx9cayyy",
    "txn_id": 806930407050,
    "txn_date": "2021-10-08T12:12:53+00:00",
    "txn_status": 3,
    "txn_type": 1,
    "issuer_name": "Сбербанк России",
    "issuer_country": "RUS",
    "card_name": "cardholder+name",
    "card_token": "d0f3c937-xxxx-yyyy-zzzz-5614c90b6199",
    "card_token_expire": "2022-05-30T21:00:00+00:00",
    "pan": "400000******0002",
    "amount": 1856,
    "currency": 643,
    "auth_code": "255723",
    "eci": "",
    "error_code": 0,
    "sign": "B9BC3C4A672FAB763519XXXXYYYYZZZZ6DA8BEE9649D6E6A8BD3A1198BE9417532B"
}

There are two types of notification flow:

• During payment processing, when card debit is confirmed and before showing status page or RSP response (depends on what flow is used, WPF or API).
• On background, when payment processed.

Notification goes to an URL which merchant provides upon integration process, or to callback_url parameter from the original request. Notification is a POST request with JSON body with the following parameters.

To minimize possible fraud notifications, RSP should verify callback signature located in sign field.

To guarantee QIWI origin of the notifications, accept only these IP addresses related to QIWI:

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

Notification is treated as successfully delivered when RSP server responds with HTTP code 200 OK. So far, during the first 24 hours after the operation, the system continue to deliver notification with incremental time intervals until RSP server responds with HTTP code 200 OK.

Industry Data

Avia

{
  "pan": "4111111111111111",
  "expiry": "1217",
  "cvv2": "002",
  "card_name": "cardholder name",
  "merchant_site": 1234,
  "cf1": "Ghbdtn",
  "opcode": 3,
  "callback_url": "testtest",
  "amount": 100,
  "currency": 643,
  "sign": "9FD874BF9D4483854E25D1D3371D01821AA4814CDFA4FE2033B5EDD4D5DE94C9",
  "industry_data": {
      "type": "avia",
      "pnr": "6Q32R2",
      "tickets": [
          {
              "number": "1",
              "passenger_name": "Ivan Ivanov",
              "amount": 500,
              "amount_total": 700,
              "restricted": false,
              "agency_code": "avi",
              "agency_name": "avia company",
              "airport_code": "air",
              "segments": [
                  {
                      "amount": 500,
                      "service_class": "A",
                      "fare_basis_code": "B",
                      "dest_city": "XYB",
                      "carrier_code": "AI",
                      "stopover_code": "X",
                      "departure_date": "2016-12-30T02:45:00Z",
                      "flight_number": "12545"
                  }
              ]
          }
      ]
  }
}

Avia data are transferred in industry_data parameter for auth, capture, sale operations of QIWI PAY API. In case of any necessary data are absent on the moment of auth operation, it can be sent in capture operation after receiving it.

Avia data should include booked tickets as well as all segments (flights) from each ticket.

Safe Purchase

Safe Purchase service from QIWI provides a transparent and reliable payment mechanism for work services without the risk of losing money for both the customer and the worker. To connect a Safe Purchase service, contact your support manager.

There are two types of safe purchase:

• With a payout on the QIWI wallet
• With a payout on the cards.

The operation is authorized by both the QIWI PAY API and the QIWI PAY WPF.

Working with partial amounts

Case Of authorization

{
  "opcode": 1,
  "merchant_uid": "10001",
  "merchant_site": 555,
  "pan": "41111111111111111",
  "expiry": "1219",
  "cvv2": "123",
  "amount": "450.20",
  "currency": 643,
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "cf1": "79323213232",
  "cf2": "250.10;200.10",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e"
}

To use the protocol of a safe purchase, you need to divide the amount of authorization into partial amounts:

• The partial amount of payouts,
• The partial amount of the commissions.

The partial amount of payouts is the funds that is paid to the worker at the end of a safe purchase.

The partial amount of commissions is the amount of commissions of the Marketplace on which the transaction is performed, and QIWI. From this amount, QIWI holds the commission for the operation service, and the remainder is transferred to the Marketplace.

The amounts are transmitted in the authorization request or on the WPF calling in the cf2 field separated by semicolon:

"cf2": "<payout partial amount>; <commissions partial amount>"

Safe purchase with a QIWI wallet payout

This type of safe purchase consists of two stages:

• Authorization of charging funds through the request to API or by calling WPF (Operation code 3).
• Confirmation of the operation (Operation code 5).

At each stage, be sure to specify the number of the QIWI Wallet in the cf1 field of the request in the format

"cf1": "79111111111"

If the transaction is confirmed, the amount to be paid is automatically credited to the QIWI Wallet specified in the request.

Case Of cancellation

{
  "opcode":6,
  "merchant_site": 10001,
  "txn_id": 181001,
  "amount": "350.00",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268",
  "cf2": "250.00;100.00"
}

The transaction can be cancelled in full or in part only until the transaction is confirmed. To cancel, make a Cancel request (Operation code 6) and specify in the cf2 field a partial amounts of the canceled transaction (in the same format as for authorization).

Safe purchase with a card payout

This type of safe purchase consists of three stages:

• Authorization of charging funds through the request to API or by calling WPF (Operation codes 1, 3).
• Confirmation of the operation (Operation Code 5).
• Payout operation (Operation Code 20).

Payout Example

{
  "opcode": 20,
  "merchant_site": "10001",
  "merchant_uid": 555,
  "card_token": "4d5b363e-a116-35f5-e053-6751080ac38e",
  "txn_id":182001,  "amount": "4678.50",
  "currency": 643,
  "card_name": "cardholder name",
  "order_id": "order1231231",
  "callback_url": "http://domain.tld/callback_service",
  "success_url": "http://domain.tld/success",
  "decline_url": "http://domain.tld/decline",
  "product_name": "Winning Payout"
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e..........................."
}

Once the operation is confirmed, there are 180 days to make the payment operation. Funds are deposited on the recipient's card within 30 minutes.

Case Of Cancellation

{
  "opcode":7,
  "merchant_site": 10001,
  "txn_id": 181001,
  "amount": "350.00",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268",
  "cf2": "250.00;100.00"
}

You can cancel the transaction in full or in part before the transaction is confirmed, and make a refund after confirmation if the payment has not yet been made.

To make cancel or refund an operation, make a Cancel (Operation code 6) or Refund (Operation code 7) requests respectively and specify in the cf2 field a partial amounts of the cancelled transaction (in the same format as for the authorization).

Receipt Info

According to Russian Federation law (54-FZ), every merchant should provide online receipts for clients due to tax regulation. QIWI PAY API provides the service for it.

Follow the steps to send receipt for the transaction:

1. Prepare JSON object of the receipt
2. Compress the object by DEFLATE algorithm according to RFC1951
3. Transform the result to ZLIB format by RFC1950

4. Send BASE64-encoded obtained string:

   • when using QIWI PAY WPF redirect — in merchant_cheque parameter
   • when using QIWI PAY API — in cheque parameter for auth, capture, sale operations.

JSON description

{
  "seller_id" : 3123011520,
  "cheque_type" : 1,
  "customer_contact" : "foo@domain.tld",
  "tax_system" : 1,
  "positions" : [
    {
      "quantity" : 2,
      "price" : 322.94,
      "tax" : 4,
      "description" : "Item/Service 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Item/Service 2"
    }
  ]
}

<?php
$cheque_json = '{
  "seller_id" : 3123011520,
  "cheque_type" : 1,
  "customer_contact" : "foo@domain.tld",
  "tax_system" : 1,
  "positions" : [
    {
      "quantity" : 2,
      "price" : 322.94,
      "tax" : 4,
      "description" : "Item/Service 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Item/Service 2"
    }
  ]
}';


$cheque = base64_encode(gzcompress($cheque_json));
?>

Output:
eJyljk0KwjAQRveeImRdtEl1oSvvIVJCGjHQNrWZgqUUFG+iFyi6FDxDeiOT+LcQV25m8d58800zQAhrkaaijGWC0QxFhEYhIRMaBs7xtdhUIoa6EM6SB6w0qMxGuMqBcXAGr5SaJypjMh9CmmC/CGwb61qDyD7hQmkJUuXaoYUlCDV+WrepWA4Saqdo8KJFKblvjygdTsdvbq87+gGJ0LyUhbvuXzJHczNn0/W7kTn1e3PtD+ZiOkSwT7TB73by3T4Jw/+r6bPazuWgvQNvoHPJ

Transaction Types

Transaction types returned in txn_type parameter are in the following table.

Transaction Statuses

Errors Description

Response with errors

Request with errors in card data

{
    "opcode": 1,
    "pan": "4",
    "expiry": "1010",
    "cvv2": "1",
    "amount": 4678.5,
    "card_name": "cardholder name",
    "merchant_site": 1000,
    "sign": "9FD874BF9D4483854E25D1D3371D01821AA4814CDFA4FE2033B5EDD4D5DE94C9"
}

Response

{
  "errors": [
    {
      "field": "pan",
      "message": "length of [pan] cannot be less than 13"
    },
    {
      "field": "expiry",
      "message": "card expired"
    },
    {
      "field": "cvv2",
      "message": "length of [cvv2] cannot be less than 3"
    }
  ],
  "error_message": "Validation errors",
  "error_code": 8024
}

Request with empty txn_id

{

  "opcode" : 6,
  "merchant_site" : "1234",
  "txn_id" : "",
  "sign" : "sadads",
  "amount" : "1000.01"
}

Response

{
  "error_message":"Parsing error",
  "error_code":8006
}

Response with errors has the following structure:

Error codes

How to Test Operations

By default, for each new RSP a merchant_site record is created in QIWI PAY service in test environment only. You can ask your support manager to transfer any of your merchant_site to test environment, or add new merchant_site in test environment.

How to make tests

• In test environment, you may use only ruble (643 code) for the currency parameter.
• CVV for payments in test environment may be arbitrary (any 3 digits).

Use production URLs for sending test requests.

To make tests of various payment methods and responses, use different expiry dates:

• If month of expiry date is 02, then operation would be unsuccessful.
• If month of expiry date is 03, then operation would be processed successfully with 3 seconds timeout.
• If month of expiry date is 04, then operation would be processed unsuccessfully with 3 seconds timeout.
• In all other cases, operation would be successful.

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 limits

Test environment has restrictions on the total amount and number of operations:

• Maximum allowed amount of a single test transaction is 10 rubles.
• Maximum number of test transactions is 100 per day (MSK time zone). Only test transactions within allowed amount are taken into account.

To process 3-D Secure operation, use unknown name as card holder name.

3-D Secure in test environment may be properly tested on real card number only.