Feedback
bss@qiwi.com
NAV
json php html shell

Introduction

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

QIWIPay supports the following: payment processing, a two-step payment confirmation, refunds, recurring payments, recurring payments cancellation, transaction status query.

Integration Methods

You can use one of the following integration methods on QIWIPay:

Service URLs

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

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

Operations

To indicate which operation is performed, use Operation code (Op.Code) in each request. Operation code should be in each RSP request to API or to WPF form payload.

The following operations are accessible through QIWIPay.

Op.Code QIWIPay WPF QIWIPay API Operation Financial? Description
1 + + sale Y One-step payment
2 - + finish_3ds Depends on scenario Return to web-site after 3DS authentication
3 + + auth N Auth request for two-step payments
5 - + capture Y Confirm auth for two-step payment
6 - + reversal N Cancel payment
7 - + refund Y Refund payment
10 + + recurring_init_sale Y Initial payment for recurring payment (one-step payment)
11 + + recurring_init_auth N Initial payment for recurring payment (two-step payment)
12 - + recurring Y Recurring payment
13 - + recurring_cancel N Cancel recurring payments
20 - + payout Y Payout operation (OCT)
30 - + status N Operation status query
40 - + get_cards_by_token N Get linked cards list
51 - + mobile_auth_init N Prepare for auth request in case of two-step scenario (from RSP)
52 - + mobile_auth_card_data N Card data transfer to perform auth (from application)

Operation Methods

QIWIPay Flows

Two payment flows can be used in QIWIPay:

Similarly, two flows to initiate recurring payments can be used:

3DS {#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 QIWIPay can be 3DS-validated if the Issuer requires 3DS authentication.

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

QIWIPay WPF

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

Payment Flow

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

Redirect to QIWIPay 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.

Parameter Required Data type Description
opcode Yes integer Op.Code (1, 3, 10, 11 only)
merchant_site Yes integer RSP site ID (issued by QIWI)
currency Yes integer Operation currency by ISO 4217
sign Yes string(64) Checksum of the request’s parameters
amount No decimal Operation amount
order_id No string(256) Unique order ID assigned by RSP system
email No string(64) Customer E-mail
country No string(3) Customer Country by ISO 3166-1
city No string(64) Customer City of residence
region No string(6) Customer Region (geo code) by ISO 3166-2
address No string(64) Customer Address of residence
phone No string(15) Customer contact phone number
cf1 No string(256) Arbitrary information about the operation, such as list of services
cf2 No string(256) Arbitrary information about the operation, such as list of services
cf3 No string(256) Arbitrary information about the operation, such as list of services
cf4 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
product_name No string(256) Service description.
merchant_uid No string(64) Unique Customer ID assigned by RSP system
order_expire No YYYY-MM-DDThh:mm:ss±hh:mm Order expiration date by ISO8601 with time zone
callback_url No string(256) Callback URL
success_url No string(256) Redirect URL when payment is successful
decline_url No string(256) Redirect URL when payment is unsuccessful

QIWIPay API

Authorization

QIWIPay 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",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (1)
merchant_site Yes integer RSP site ID (issued by QIWI)
pan Yes string(19) Card number (PAN)
expiry Yes string(4) Card expiry date
card_token Yes, if available string(40) Card token
cvv2 Yes string(4) CVV2/CVC2 code
amount Yes decimal Operation amount
currency Yes integer Operation currency by ISO 4217
sign Yes string(64) Checksum of the request’s parameters
card_name Yes, if available string(64) Cardholder name as printed on the card (Latin letters)
order_id Yes, if available string(256) Unique order ID assigned by RSP system
ip Yes, if available string(15) Customer IP address
email Yes, if available string(64) Customer E-mail
country Yes, if available string(3) Customer Country by ISO 3166-1
user_device_id Yes, if available string(64) Customer Unique device ID
city Yes, if available string(64) Customer City of residence
region Yes, if available string(6) Customer Region (geo code) by ISO 3166-2
address Yes, if available string(64) Customer Address of residence
phone Yes, if available string(15) Customer contact phone number
user_timedate No string(64) Local time in Customer browser
user_screen_res No string(64) Screen resolution of the Customer’s display
user_agent No string(256) Customer browser
cf1 No string(256) Arbitrary information about the operation, such as list of services
cf2 No string(256) Arbitrary information about the operation, such as list of services
cf3 No string(256) Arbitrary information about the operation, such as list of services
cf4 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
product_name No string(256) Service description.
merchant_uid No string(64) Unique Customer ID assigned by RSP system
order_expire No YYYY-MM-DDThh24:mm:ss Order expiration date by ISO8601
callback_url No string(256) Callback URL
cheque No string Receipt data

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":
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, in ISO8601 with timezone
card_token string(40) Card token (if tokenization is enabled for the merchant site)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm Expiry date for the card token (if tokenization is enabled for the merchant site)
error_code integer System error code
pan string(19) Customer Card number (PAN)
issuer_name string(40) Issuer bank name
issuer_country string(3) Issuer bank country
amount decimal Amount to debit from card account
currency integer Operation currency by ISO 4217
auth_code string(6) Authorization code
eci string(2) Electronic Commerce Indicator

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....."
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code
acs_url string(1024) Issuing Bank URL where to redirect Customer
pareq string(4096) Unique Customer ID to use for acs_url redirect.

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"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (2)
merchant_site Yes integer RSP site ID (issued by QIWI)
pares Yes string(4096) Customer verification result
txn_id Yes integer Transaction ID
sign Yes string(64) Checksum of the request’s parameters

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"
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
card_token string(40) Card token (if tokenization is enabled for the merchant site)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm Expiry date for the card token (if tokenization is enabled for the merchant site)
error_code integer System error code
pan string(19) Customer Card number (PAN)
issuer_name string(40) Issuer bank name
issuer_country string(3) Issuer bank country
amount decimal Amount to debit from card account
currency integer Operation currency by ISO 4217
auth_code string(6) Authorization code
eci string(2) Electronic Commerce Indicator

Sale Confirmation Operation

Request

{
  "opcode": 5,
  "merchant_site": 99,
  "txn_id": "172001",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (5)
merchant_site Yes integer RSP site ID (issued by QIWI)
txn_id Yes integer Transaction ID
cheque No string Receipt data
sign Yes string(64) Checksum of the request’s parameters

Response

{
  "txn_id":172001,
  "txn_status":60,
  "txn_type":1,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code

Cancel Operation

Request

{
  "opcode":6,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (6)
merchant_site Yes integer RSP site ID (issued by QIWI)
txn_id Yes integer Transaction ID
amount No decimal Operation amount
sign Yes string(64) Checksum of the request’s parameters
cheque No string Receipt data

Response

{
  "txn_id":182001,
  "txn_status":72,
  "txn_type":4,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code
amount decimal Amount to debit

Refund Operation

Request

{
  "opcode":7,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (7)
merchant_site Yes integer RSP site ID (issued by QIWI)
txn_id Yes integer Transaction ID
amount No decimal Operation amount
sign Yes string(64) Checksum of the request’s parameters
cheque No string Receipt data

Response

{
  "txn_id":182001,
  "txn_status":77,
  "txn_type":3,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 700
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code
amount decimal Amount to debit

Recurring Payment Operation

Request

{
  "opcode": 12,
  "merchant_uid": "10001",
  "merchant_site": 99,
  "txn_id": 172001,
  "amount": 4678.5,
  "currency": 643,
  "order_id": "order1231231",
  "cf1": "cf1",
  "cf2": "cf2",
  "cf3": "cf3",
  "cf4": "cf4",
  "cf5": "cf5",
  "product_name": "Название услуги",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (12)
merchant_site Yes integer RSP site ID (issued by QIWI)
txn_id Yes integer Transaction ID
amount Yes decimal Operation amount
sign Yes string(64) Checksum of the request’s parameters
order_id Yes, if available string(256) Unique order ID assigned by RSP system
cf1 No string(256) Arbitrary information about the operation, such as list of services
cf2 No string(256) Arbitrary information about the operation, such as list of services
cf3 No string(256) Arbitrary information about the operation, such as list of services
cf4 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
product_name No string(256) Service description.
cheque No string Receipt data

Response

{
  "txn_id":182001,
  "txn_status":60,
  "txn_type":5,
  "txn_date": "2017-03-09T17:16:06+00:00",
  "error_code":0,
  "amount": 4678.5,
  "currency": 643,
  "auth_code": "2G4923"
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code
amount decimal Amount to debit
currency integer Operation currency by ISO 4217
auth_code string(6) Authorization code

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": "Выплата выигрыша",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e..........................."
}
Parameter Required Data type Description
opcode Yes integer Op.Code (12)
merchant_site Yes integer RSP site ID (issued by QIWI)
card_token string(40) Card token (if tokenization is enabled for the merchant site)  
txn_id Yes integer Transaction ID
amount Yes decimal Operation amount
currency Yes integer Operation currency by ISO 4217
card_name Yes, if available string(64) Cardholder name as printed on the card (Latin letters)
order_id Yes, if available string(256) Unique order ID assigned by RSP system
cf1 No string(256) Arbitrary information about the operation, such as list of services
cf2 No string(256) Arbitrary information about the operation, such as list of services
cf3 No string(256) Arbitrary information about the operation, such as list of services
cf4 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
sign Yes string(64) Checksum of the request’s parameters
callback_url No string(256) Callback URL
product_name No string(256) Service description.
cheque No string Receipt data

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"
}
Parameter Data type Description
txn_id integer Transaction ID
txn_status integer Transaction status
txn_type integer Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone
error_code integer System error code
pan string(19) Card number
amount decimal Amount to pay
currency integer Operation currency by ISO 4217
auth_code string(6) Authorization code

Status Query Operation

Request

{
  "opcode":30,
  "merchant_site": 99,
  "order_id": "41324123412342",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Op.Code (30)
merchant_site Yes integer RSP site ID (issued by QIWI)
txn_id Yes integer Transaction ID
sign Yes string(64) Checksum of the request’s parameters
order_id No string(256) Unique order ID assigned by RSP system

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
}
Parameter Data type Description  
txn_id integer Transaction ID  
txn_status integer Transaction status  
txn_type integer Transaction type  
txn_date YYYY-MM-DDThh:mm:ss±hh:mm Transaction date, by ISO8601 with timezone  
error_code integer System error code  
pan string(19) Masked Card number (PAN), first six and last four digits are unmasked  
amount decimal Amount to debit  
currency integer Operation currency by ISO 4217  
auth_code string(6) Authorization code  
eci string(2) Electronic Commerce Indicator  
card_name string(64) Cardholder name as printed on the card (Latin letters)  
card_bank string(64) Issuing Bank  
order_id string(256) Unique order ID assigned by RSP system  
ip string(15) Customer IP address  
email string(64) Customer E-mail  
country string(3) Customer Country by ISO 3166-1  
city string(64) Customer City of residence  
region string(6) Customer Region (geo code) by ISO 3166-2  
address string(64) Customer Address of residence  
phone string(15) Customer contact phone number  
cf1 No string(256) Arbitrary information about the operation, such as list of services
cf2 No string(256) Arbitrary information about the operation, such as list of services
cf3 No string(256) Arbitrary information about the operation, such as list of services
cf4 No string(256) Arbitrary information about the operation, such as list of services
cf5 No string(256) Arbitrary information about the operation, such as list of services
product_name string(256) Service description.  

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",
  "industryData": {
      "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 QIWIPay 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.

Parameter Required Data type Description
type Y string Data type (only avia)
pnr N string(6) Booking number
tickets Y array Bunch of tickets
number Y string(14) Ticket number
passenger_name Y string(20) Passenger name
amount Y decimal Ticket price without airport fee
amount_total Y decimal Ticket price with airport fee
restricted Y boolean Restricted Ticked Indicator
agency_code Y string(8) Travel agency code
agency_name Y string(25) Travel agency title
airport_code Y string(3) Airport of departure (3 letters by IATA code)
segments Y array Avia segments
amount Y decimal Ticket price for the segment
service_class Y string(1) Flight service class
fare_basis_code Y string(6) Flight fare code
dest_city Y string(3) Airport of destination (3 letters by IATA code)
carrier_code Y string(2) Airline code
stopover_code Y string(1) Stop-Over Code
departure_date Y YYYY-MM-DDThh:mm:ss±hh:mm Departure date, ISO8601 with timezone
flight_number Y string(5) Flight number, digits only

Receipt Info

{
  "seller_id" : 3123011520,
  "cheque_type" : 1,
  "customer_contact" : "foo@domain.tld",
  "tax_system" : 1,
  "positions" : [
    {
      "quantity" : 2,
      "price" : 322.94,
      "tax" : 4,
      "description" : "Товар/Услуга 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Товар/Услуга 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" : "Товар/Услуга 1"
    },
    {
      "quantity" : 1,
      "price" : 500,
      "tax" : 4,
      "description" : "Товар/Услуга 2"
    }
  ]
}';


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

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

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

Receipt may be transferred two-ways:

Receipt’s JSON structure have to be compressed by DEFLATE algorithm according to RFC1951, then transformed to ZLIB format by RFC1950 and BASE64-encoded.

JSON description

Parameter Required Data type Description
seller_id Y decimal Organization TIN (taxpayer identification number)
cheque_type Y decimal Receipt type (tag 1054 in the tax document) - one of the following:
1. Приход
2. Возврат прихода
3. Расход
4. Возврат расхода
customer_contact Y string(64) Customer phone or e-mail (tag 1008 in the tax document)
tax_system Y decimal Tax system applied to merchant (tag 1055 in the tax document):
0 – Общая, ОСН
1 – Упрощенная доход, УСН доход
2 – Упрощенная доход минус расход, УСН доход - расход
3 – Единый налог на вмененный доход, ЕНВД
4 – Единый сельскохозяйственный налог, ЕСН
5 – Патентная система налогообложения, Патент
positions Y array Items
quantity Y decimal Goods quantity (tag 1023 in the tax document)
price Y decimal Price per item of goods, with discounts and markups (tag 1079 in the tax document)
tax Y decimal VAT rate (tag 1199 in the tax document):
1 – 18%
2 – 10%
3 – расч. 18/118
4 – расч. 10/110
5 – 0%
6 – not applicable
description Y string(128) Goods description

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);
    }
}

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

Для параметров amount|currency|merchant_site|opcode

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

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e
Для параметров amount|currency|merchant_site|opcode

user@server:~$ echo -n "7.00|643|555|3" | openssl dgst -sha256  -hmac "secret_key"
(stdin)= 9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

You should sign all parameters in 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.

Payment Notification

There are two types of notification flow:

Notification goes to callback_url parameter from the original request, as a POST request with the following parameters.

Parameter Datat type Used for signature Description
txn_id integer + Transaction ID
txn_status integer + Transaction status
txn_type integer + Transaction type
txn_date YYYY-MM-DDThh:mm:ss±hh:mm - Transaction date, by ISO8601 with timezone
error_code integer + System error code
pan string(19) - Customer Card number (PAN), first six and last four digits are unmasked
amount decimal + Amount to debit
currency integer + Operation currency by ISO 4217
auth_code string(6) - Authorization code
eci string(2) - Electronic Commerce Indicator
card_name string(64) - Cardholder name as printed on the card (Latin letters)
card_bank string(64) - Issuing Bank
order_id string(256) - Unique order ID assigned by RSP system. Returned if sent in the original request.
ip string(15) + Customer IP address
email string(64) + Customer E-mail
country string(3) - Customer Country by ISO 3166-1
city string(64) - Customer City of residence
region string(6) - Customer Region (geo code) by ISO 3166-2
address string(64) - Customer Address of residence
phone string(15) - Customer contact phone number
cf1 string(256) - Arbitrary information about the operation, such as list of services
cf2 string(256) - Arbitrary information about the operation, such as list of services
cf3 string(256) - Arbitrary information about the operation, such as list of services
cf4 string(256) - Arbitrary information about the operation, such as list of services
cf5 string(256) - Arbitrary information about the operation, such as list of services
product_name string(256) - Service description
card_token string(40) - Card token (if tokenization is enabled for the merchant site)
card_token_expire YYYY-MM-DDThh:mm:ss±hh:mm - Expiry date for the card token (if tokenization is enabled for the merchant site)
sign string(64) - Checksum (signature) of the request

RSP should verify request signature (sign parameter) to minimize possible fraud notifications.

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

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 will continue to deliver notification with incremental time intervals until RSP server responds with HTTP code 200 OK.

Transaction Types

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

Type Name Description
1 Purchase One-step payment
2 Purchase Authorization for two-step payment
6 Purchase One-step operation for initial recurring payment
7 Purchase Authorization for two-step initial recurring payment
4 Reversal Cancel operation
3 Refund Refund operation
5 Recurring Recurring payment operation
8 Payout Payout operation (OCT)
0 Unknown Unknown operation type

Transaction Statuses

Status Name Description Possible operations
0 Init Base verification is passed and operation begins to process -
1 Declined Operation declined -
2 Authorized Authorization is passed (hold) capture, reversal
3 Captured (Completed) Confirmed operation reversal
4 Reconciled Completely finished financial operation refund
5 Settled RSP is paid for this operation refund

Errors Description

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

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

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

Error code Name Description
0 No errors No errors
8001 Internal error Acquiring Bank technical error
8002 Operation not supported Operation not supported
8004 Temporary error Server is busy, repeat later
8005 Route not found Route for transaction processing not found
8006 Parsing error Unable to process input request, incorrect format
8018 Transaction not found Transaction not found
8019 Incorrect opcode  
8020 Amount too big reversal, refund operations amount exceeded
8021 Merchant site not found Unknown merchant with merchant_site_id
8022 Transaction not found Transaction from the request not found.
8023 Transaction expired Customer failed to authorize on 3DS within 15 min
8025 Opcode is not allowed Using this opcode forbidden for this merchant site
8026 Incorrect parent transaction Incorrect status of the parent transaction
8027 Incorrect parent transaction Incorrect type of the parent transaction
8028 Card expired Card valid date is expired
8051 Merchant disabled This merchant is not activated.
8052 Incorrect transaction state Incorrect transaction status, attempt for capture after finish_3ds or reversal
8054 Invalid signature Invalid signature of the request
8055 Order already paid  
8056 In process Transaction on this card/order is processing now.
8057 Card locked Transaction is already processing upon this card
8058 Access denied  
8059 Currency is not allowed  
8060 Amount too big Amount is higher than allowed for payout.
8061 Currency mismatch Payout currency and original transaction currency are not the same
8151 Authentification failed Customer failed to authenticate on 3DS.
8152 Transaction rejected Transaction rejected by security service.
8160 Transaction rejected Issuer response: Payment rejected. Try again
8161 Transaction rejected Issuer response: Payment rejected. Try again
8162 Transaction rejected Issuer response: Payment rejected. Try again
8163 Transaction rejected Issuer response: Payment rejected. Contact QIWI Support
8164 Transaction rejected Issuer response: Payment rejected. Limit exceeded. Address to Issuing Bank
8165 Transaction rejected Issuer response: Payment rejected. Check payment details
8166 Transaction rejected Issuer response: Payment rejected. Check card details
8167 Transaction rejected Issuer response: Payment rejected. Check card details
8168 Transaction rejected Issuer response: Transaction forbidden. Address to Issuing Bank
8169 Transaction rejected Issuer response: Payment rejected. Limit exceeded. Address to Issuing Bank

Test Data

Use production url for testing purposes.

By default, for each new RSD merchant_site is created in QIWI Pay system in testing mode. You can ask your manager to make testing mode of any of your merchant_site, or add new merchant_site in testing mode.

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

To process 3DS operation, use unknown name as card holder name.

3DS in testing mode may be properly tested on real card number.