title

metatitle

metadescription

General Information

Edit on GitHub

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

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

Integration Methods

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

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

QIWI PAY API requests with full card numbers are allowed by PCI DSS-certified merchants only, as Card Data are processed on the merchant's side.

Service URLs {#urls}

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

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

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

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

Operations {#opcode}

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

Financial operation means that there is cash flow on bank accounts.

Operation Methods {#methods}

QIWI PAY Flows

Two payment flows can be used in QIWI PAY:

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

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

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

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

The longest period between auth and capture operations is 72 hours. Therefore, if no capture operation comes within 72 hours from RSP since auth is received, it is performed anyway.

3DS {#threeds}

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

In case of the two-step flow, use only the first operation (auth).

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 {#api}

Authorization {#api_auth}

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

To obtain certificate, please submit certificate request in .csr PKCS#10 format to QIWI Support (bss@qiwi.com).

Payment Flow {#flows}

One-step payment flow {#onestep}

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 {#twostep}

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 {#sale}

Request {#sale-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 {#sale_no3ds}

{
  "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 {#sale_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 {#finish_3ds}

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 {#finish-request}

{
  "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 {#finish-response}

{
  "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 {#sale_confirm}

Request {#confirm-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 {#confirm-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 {#cancel}

Request {#cancel-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 {#cancel-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 {#refund}

Request {#refund-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 {#refund-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 {#payout}

Request {#payout-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 {#payout-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 {#status}

Request {#status-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 {#status-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 {#sign}

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

For parameters string amount|currency|merchant_site|opcode

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

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

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

Output:
9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

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

(stdin)= 9c878bfbf9baa30c26c8c6206976fc3ed2c036afeabf352f8a045fe331d42d7e

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

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

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

Payment Notification {#callback}

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

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

There are two types of notification flow:

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

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

Callback is sent by HTTPS protocol on 443 port only. Certificate should be issued by any trusted center of certification (e.g. Comodo, Verisign, Thawte etc)

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.

Signature algorithm coincides with that of API requests, though only the parameters marked above with a plus sign in Used for signature column are taken.

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

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

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

Due to any reason, if RSP accepts notification without HTTP code 200 OK then the same transaction on the repeated notification should not be treated as the new one. RSP is solely responsible for possible financial loss when sign is not verified for the illegal notifications.

Industry Data {#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_deal}

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

There are two types of safe purchase:

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

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

Working with partial amounts {#safe_deal_subsums}

Case Of authorization

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

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

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

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

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

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

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

Amount of authorization (amount value) should equal the sum of its partial amounts. Example:
"amount": "500.00"
"cf2": "300.00; 200.00"

Safe purchase with a QIWI wallet payout {#safe_deal_wallet}

This type of safe purchase consists of two stages:

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

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

"cf1": "79111111111"

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

Max waiting time between authorization and confirmation is 5 days

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

Amount of cancel operation (amount value) should equal the sum of its partial amounts.

Safe purchase with a card payout {#safe_deal_card}

This type of safe purchase consists of three stages:

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

Payout Example

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

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

Organizations without PCI DSS can only make payments using card tokens.

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

Amount to cancel (amount value) should equal the sum of its partial amounts.

Receipt Info {#cheque}

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:

Prepare JSON object of the receipt
Compress the object by DEFLATE algorithm according to RFC1951
Transform the result to ZLIB format by RFC1950
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.

When your account is in test mode, the receipt is processed in test environment.

JSON description {#json_receipt}

{
  "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 {#txn_type}

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 {#txn_status}

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`

If interaction with Acquiring bank is online, then status 4 is returned in case of sale, capture operations.

If interaction with Acquiring bank is made via postponed approval of financial operations, then status 3 is returned after sale, capture operations, while status 4 is returned after sending financial information on status query operation.

Status 2 and higher means that funds are authorized and you may already provide service/goods.

Errors Description {#errors}

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's parameter caused the error
errors[].message	String	Error text description

Error codes {#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 pay system	Operation rejected by Payment system. Re-attempting the operation is not possible for the card.

How to Test Operations {#test_mode}

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.

To make tests for payment operations, you may use any card number satisfying to Luhn algorithm.
In test environment, you may use only ruble (643 code) for the currency parameter.
CVV for payments in test environment may be arbitrary (any 3 digits).

Use production URLs for sending test requests.

Test card numbers

Get more cards

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

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

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

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

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

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

Files

qiwipay_en.html.md

Latest commit

History

qiwipay_en.html.md

File metadata and controls

General Information

Edit on GitHub

Integration Methods

Service URLs {#urls}

Operations {#opcode}

Operation Methods {#methods}

QIWI PAY Flows

3DS {#threeds}

QIWI PAY WPF {#wpf}

Payment Flow

Redirect to QIWI PAY WPF

QIWI PAY API {#api}

Authorization {#api_auth}

Payment Flow {#flows}

One-step payment flow {#onestep}

Two-step payment flow {#twostep}

Sale Operation {#sale}

Request {#sale-request}

Response for card with no 3DS {#sale_no3ds}

Response for card with 3DS {#sale_3ds}

Finish 3DS authentication {#finish_3ds}

Request after successful 3DS authentication {#finish-request}

Response to 3DS authentication result {#finish-response}

Sale Confirmation Operation {#sale_confirm}

Request {#confirm-request}

Response {#confirm-response}

Cancel Operation {#cancel}

Request {#cancel-request}

Response {#cancel-response}

Refund Operation {#refund}

Request {#refund-request}

Response {#refund-response}

Payout Operation {#payout}

Request {#payout-request}

Response {#payout-response}

Status Query Operation {#status}

Request {#status-request}

Response {#status-response}

Signature of the Request {#sign}

Payment Notification {#callback}

Industry Data {#industry_data}

Avia

Safe Purchase {#safe_deal}

Working with partial amounts {#safe_deal_subsums}

Safe purchase with a QIWI wallet payout {#safe_deal_wallet}

Safe purchase with a card payout {#safe_deal_card}

Receipt Info {#cheque}

JSON description {#json_receipt}

Transaction Types {#txn_type}

Transaction Statuses {#txn_status}

Errors Description {#errors}

Response with errors

Error codes {#codes}

How to Test Operations {#test_mode}

Test card numbers