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

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:

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 in opcode parameter of each request to API or on loading WPF pay form.

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

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(255, 238, 223) 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(255, 238, 223) 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(255, 238, 223) 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(255, 238, 223) 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(255, 238, 223) 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: Authorization request activate QiwiBank QiwiBank-->>QiwiPay: Successful authorization deactivate QiwiBank rect rgb(255, 238, 223) 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",
  "receiver_name": "Ivanov, Ivan",
  "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
wallet_type No string(50) Type of a wallet to top up. Possible values: QIWI
account_id No integer(50) Number of a wallet to top up. Required if wallet_type=QIWI is in the operation
receiver_name No string(30) Last and first name of the payment's receiver separated by , (comma followed by space). Order matters: last name should be before first name. Only Latin letters, digits, and symbols _, - (first name can be with spaces).
receiver_pan Yes, if available string(19) Card number of the money transfer recipient. Specified for money transfer operations.
receiver_bank_account Yes, if available string(20) Recipient's account number. Specified for money transfer operations.
receiver_bic Yes, if available string(9) BIC of the credit institution of the recipient. Specified for money transfer operations.
receiver_wallet Yes, if available string(64) Recipient's wallet number. Specified when replenishing the wallet.
receiver_inn Yes, if available string(12) TIN of the organization that issued the wallet. Specified when replenishing the wallet.
receiver_phone Yes, if available string(15) Recipient's phone number. Specified when replenishing the phone.
upper_commission_taken No string Field to put upper commission in.

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

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.

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:

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.

Callback field 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)
issuer_name string(64) - Bank Issuer
issuer_country string(3) - Country of bank issuer
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

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:

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.

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

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:

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

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:

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

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

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:

Field Type Description
error_code Number Error code
error_message String Error description
errors Array of Objects Detailed description of errors
errors[].field String Name of the request parameter caused the error
errors[].message String Error text description

Error codes

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.
8008 No receiver data Error on transmitting receiver data.
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.
8062 Temporary error Server is busy, repeat the request later.
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.
8153 Reattempt not permitted Re-attempting authorization request is forbidden due to Payment system rules.
8154 Try again later Repeat the request later.
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.
8170 Transaction rejected Issuer response: Payment rejected. Wrong SMS code. Try again.
8171 Reattempt not permitted by payment system Operation rejected by Payment system. Re-attempting the operation is not possible for the card.

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

Use production URLs for sending test requests.

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

Test card numbers

Test limits

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

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.