Feedback
bss@qiwi.com
NAV Navbar
JSON PHP HTML Java shell

Introduction

Last update: 2020-04-28 | 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:

Service URLs

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

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

Operations

To indicate which operation is performed, you need to specify Operation code (Op.Code) in each request to API or on loading WPF pay form. Operation code should be in each RSP request to API or to WPF form payload.

The following operations are accessible through QIWI PAY.

Op.Code QIWI PAY WPF QIWI PAY 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 (funds returned almost immediately)
7 - + refund Y Refund payment (funds returned within 30 days)
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

QIWI PAY Flows

Two payment flows can be used in QIWI PAY:

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.

sequenceDiagram participant Customer participant Issuer participant ips as Visa/MC participant qp as QIWI PAY participant qb as QIWI Bank Note over Customer,Issuer: Issuer Domain Note over ips: Interaction Domain Note over qp,qb: Acquirer Domain Customer->>qp:Send card data from payment web-form activate Customer activate qp qp->>ips:Send VEReq
to verify card for
3-D Secure enrollment activate ips ips->>Issuer:Request to ACS
to verify card enrollment activate Issuer Issuer-->>ips:Return verify response (VERes) deactivate Issuer ips-->>qp:Return verify response (VERes) deactivate ips qp->>qp:PAReq generation from VERes qp-->>Customer:Redirect from PAReq to ACS URL
taken from VERes
to enter 3-D Secure password deactivate qp deactivate Customer Customer->>Issuer:Redirect to ACS URL activate Customer activate Issuer Issuer-->>Customer:One-time password SMS Customer->>Issuer:Enter one-time password Issuer->>ips:Send ACS authentication
result data Issuer-->>Customer:Redirect to
QIWI PAY page
with PARes deactivate Customer deactivate Issuer Customer->>qp:Redirect to QIWI PAY page activate Customer activate qp qp->>qp:PARes validity verification qp->>qb:Authorization request
with PARes data deactivate qp deactivate Customer

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.

sequenceDiagram participant Customer participant Merchant participant QiwiPay as QIWI PAY participant QiwiBank as QIWI Bank Customer->>Merchant:Placing order,
choose card payment activate Merchant Merchant-->>Customer:Redirect to payment web-form deactivate Merchant Customer->>QiwiPay:Request for payment web-form activate QiwiPay QiwiPay-->>Customer:Payment web-form deactivate QiwiPay Customer->>QiwiPay:Enter card data and submit form activate QiwiPay QiwiPay->>QiwiPay:Initial verification of parameters,
creating transaction QiwiPay->>QiwiPay:Anti-fraud module rect rgb(237, 243, 255) Note over Customer, QiwiPay: 3-D Secure QiwiPay->>QiwiPay:Verify card for 3-D Secure enrollment QiwiPay-->>Customer:Redirect to ACS URL deactivate QiwiPay Customer->>QiwiPay:Return from ACS page
with 3-D Secure verification results activate QiwiPay end QiwiPay->>QiwiBank:Authorization request activate QiwiBank QiwiBank-->>QiwiPay:Successful authorization deactivate QiwiBank rect rgb(237, 243, 255) Note over Customer, QiwiPay: Immediate notification QiwiPay->>Merchant:Notification on operation
result (callback) activate Merchant Merchant-->>QiwiPay:Confirm receiving
notification deactivate Merchant end QiwiPay->>Customer:Status page with operation result QiwiPay->>Customer:E-mail notification deactivate QiwiPay Customer->>Merchant:Return to shop
web-site from
status page

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.

Parameter Required Data type Description
opcode Yes integer Operation code (1, 3 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(25) Service description for the Customer
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

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

sequenceDiagram participant Customer participant Merchant participant QiwiPay as QIWI PAY participant QiwiBank as QIWI Bank Customer->>Merchant:Send card data
from payment web-form activate Merchant Merchant->>QiwiPay:"sale" operation
request activate QiwiPay QiwiPay->>QiwiPay:Anti-fraud module rect rgb(237, 243, 255) Note over Customer, QiwiPay: 3-D Secure QiwiPay->>QiwiPay:Check card
3-D Secure enrollment QiwiPay-->>Merchant:Redirect ACS
Issuing Bank parameters
for Customer deactivate QiwiPay Merchant-->>Customer:Redirect to ACS URL deactivate Merchant Customer->>Merchant:Return with 3-D Secure
verificaiton result activate Merchant Merchant->>QiwiPay:"finish_3ds" operation
request activate QiwiPay end QiwiPay->>QiwiBank:Authorization request activate QiwiBank QiwiBank-->>QiwiPay:Successful authorization QiwiPay->>QiwiBank:Authorized financial operation QiwiBank-->>QiwiPay:Confirmed financial operation deactivate QiwiBank rect rgb(237, 243, 255) Note over Customer, QiwiPay: Immediate notification QiwiPay->>Merchant:Notification on
operation result (callback) activate Merchant Merchant-->>QiwiPay:Confirm receiving notification deactivate Merchant end QiwiPay->>Merchant:Operation result QiwiPay->>Customer:E-mail notification deactivate QiwiPay Merchant->>Customer:Status page
with operation result deactivate Merchant

Two-step payment flow

sequenceDiagram participant Customer participant Merchant participant QiwiPay as QIWI PAY participant QiwiBank as QIWI Bank Customer->>Merchant:Send card data
from payment web-form activate Merchant Merchant->>QiwiPay:
"auth" operation
request activate QiwiPay QiwiPay->>QiwiPay:Anti-fraud module rect rgb(237, 243, 255) Note over Customer, QiwiPay: 3-D Secure QiwiPay->>QiwiPay:Check card 3-D Secure
enrollment QiwiPay-->>Merchant:Redirect ACS Issuing Bank
parameters for Customer deactivate QiwiPay Merchant-->>Customer:Redirect to ACS URL deactivate Merchant Customer->>Merchant:Return with 3-D Secure
verification result activate Merchant Merchant->>QiwiPay:"finish_3ds" operation
request activate QiwiPay end QiwiPay->>QiwiBank: Auhtorization request activate QiwiBank QiwiBank-->>QiwiPay: Successful authorization deactivate QiwiBank rect rgb(237, 243, 255) Note over Customer, QiwiPay: Immediate notification QiwiPay->>Merchant:Notification on
operation result (callback) activate Merchant Merchant-->>QiwiPay:Confirm receiving notification deactivate Merchant end QiwiPay->>Merchant:Operation result QiwiPay->>Customer:E-mail notification deactivate QiwiPay Merchant->>Customer:Status page
with operation result deactivate Merchant Note over Merchant: Awaiting for request confirming authorization Merchant-->>QiwiPay:"capture" operation
request activate Merchant activate QiwiPay QiwiPay->>QiwiBank:Financial operation
after authorization activate QiwiBank QiwiBank-->>QiwiPay:Confirmed financial operation deactivate QiwiBank QiwiPay->>Merchant:Notification on
operation result (callback) deactivate QiwiPay deactivate Merchant

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

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

Parameter Required Data type Description
opcode Yes integer Operation code (1, 3)
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(25) Service description for the Customer
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": "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, in ISO8601 with time zone
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
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no card debiting is made

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 time zone
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.
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no card debiting is made

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 Operation 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 time zone
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
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no card debiting is made

Sale Confirmation Operation

Request

{
  "opcode": 5,
  "merchant_site": 99,
  "txn_id": "172001",
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Operation 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 time zone
error_code integer System error code
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no card debiting is made

Cancel Operation

Request

{
  "opcode":6,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Operation 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 time zone
error_code integer System error code
amount decimal Amount to debit
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no real funds return to card is made

Refund Operation

Request

{
  "opcode":7,
  "merchant_site": 99,
  "txn_id": 181001,
  "amount": 700,
  "sign": "bb5c48ea540035e6b7c03c8184f74f09d26e9286a9b8f34b236b1bf2587e4268"
}
Parameter Required Data type Description
opcode Yes integer Operation 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 time zone
error_code integer System error code
amount decimal Amount to debit
is_test string(4) Presence of this parameter with true value indicates that transaction is processed in testing mode and no real funds return to card is made

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..........................."
}
Parameter Required Data type Description
opcode Yes integer Operation code (20)
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(25) Service description for the Customer
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 time zone
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 Operation 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 time zone
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 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(25) Service description for the Customer

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.

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 time zone
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" : "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

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:

JSON structure of a receipt 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 - Incoming cash
2 - Cash return
3 - Outcoming cash
4 - Outcoming cash return
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 – General, "ОСН"
1 – Simplified income, "УСН доход"
2 – Simplified income minus expense, "УСН доход - расход"
3 – United tax to conditional income, "ЕНВД"
4 – United agriculture tax, "ЕСН"
5 – Patent tax system, "Патент"
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
payment_method Y decimal Cash type (tag 1214 in the tax document):
1 – payment in advance 100%. Full payment in advance before commodity provision
2 – payment in advance. Partial payment before commodity provision
3 – prepayment
4 – full payment, taking into account prepayment, with commodity provision
5 – partial payment and credit payment. Partial payment for the commodity at the moment of delivery, with future credit payment.
6 – credit payment. Commodity is delivered with no payment at the moment and future credit payment is expected.
7 – payment for the credit. Commodity payment after its delivery with future credit payment.
payment_subject Y decimal Payment subject (tag 1212 in the tax document):
1 – commodity except excise commodities (name and other properties describing the commodity).
2 – excise commodity (name and other properties describing the commodity).
3 – work (name and other properties describing the work). .
4 – service (name and other properties describing the service).
5 – gambling rate (in any gambling activities).
6 – gambling prize payment (in any gambling activities)в.
7 – lottery ticket payment (in accepting payments for lottery tickets, including electronic ones, lottery stakes in any lottery activities).
8 – lottery prize payment (n any lottery activities).
9 – provision of rights to use intellectual activity results.
10 – payment (advance, pre-payment, deposit, partial payment, credit, fine, bonus, reward, or any similar payment subject).
11 – agent's commission (in any fee to payment agent, bank payment agent, commissioner or other agent service).
12 – multiple payment subject (in any payment constituent subject to any of the above).
13 – other payment subject not related to any of the above.

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

For parameters string amount|currency|merchant_site|opcode

<?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 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 Data 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 time zone
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(25) - Service description for the Customer
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
4 Reversal Cancel operation
3 Refund Refund 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 value 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
8069 Quantity limit of transactions is reached The number of testing operations per day exceeds the limit
8070 Amount of transaction is bigger than allowed Test operation amount exceeds the allowed value
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 URLs for testing purposes.

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.

Test card numbers

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

Test environment has restrictions on the total amount and number of operations. By default, maximum amount of 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 3DS operation, use unknown name as card holder name.

3DS in test environment may be properly tested on real card number.