2.1. Qiwi Integration

2.1.1. Qiwi API URL

Qiwi transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/qiwi-invoice/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only Payneteasy object which is exposed via API. Qiwi integration allows merchant to accept customer payments made using Qiwi.

2.1.2. Qiwi Transaction Flow

Merchant initiates a transaction by sending HTTPS POST request to the Qiwi API URL and specifies the parameters according to Qiwi Request Parameters
Payneteasy Server returns response described in Qiwi Response. Merchant than checks status repeatedly until he gets terminal status (approved/declined/filtered/error) or until he gets an HTML that should be sent directly to customer browser.
Merchant sends that html to customer’s browser causing customer to be redirected to Qiwi processor.
Customer hits processor page.
Processor bills a Qiwi invoice.
Customer pays invoice.
Processor notifies Payneteasy that invoice is payed.
Payneteasy makes a callback to Merchant using server_callback_url passed with the request
Customer is returned to merchant site using redirect

2.1.3. Qiwi Request

Qiwi Request Parameters Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
amount 10/Numeric Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents Mandatory
currency 3/String USR, RUB and so on. Mandatory
phone 10/String Customer mobile phone number. Exactly 10 digits. This will be the phone number to which invoice will be billed in Qiwi system. Mandatory
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
first_name 50/String Customer’s first name Optional
last_name 50/String Customer’s last name Optional
ssn 32/Numeric Last four digits of the customer’s social security number. Optional
birthday 8/Numeric Customer’s date of birth, in the format MMDDYY. Optional
address1 50/String Customer’s address line 1. Optional
city 50/String Customer’s city. Optional
state 2/String Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia. Optional
zip_code 10/String Customer’s ZIP code Optional
country 2/String Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. Optional
email 50/String Customer’s email address. Optional
redirect_url 128/String URL the customer will be redirected to upon completion of the transaction. Please note that the customer will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if both redirect_success_url and redirect_fail_url are missing
redirect_success_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if redirect_url parameter is missing
redirect_fail_url 1024/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory if redirect_url parameter is missing
server_callback_url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional
purpose 128/String Payment destination (for instance, player nickname). Generally optional, but may be required by some Qiwi processors

* leading and trailing whitespace in input parameters will be omitted

2.1.4. Qiwi Response

Qiwi Response Parameter Description
type The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
status See Status List for details.
paynet-order-id Order id assigned to the order by Payneteasy
merchant-order-id Merchant order id
serial-number Unique number assigned by Payneteasy server to particular request from the Merchant.
error-message If status is error this parameter contains the reason for decline or error details
error-code The error code is case of error status

2.1.5. Order status

After merchant has initiated transaction, he must poll status to get html which must be fed to the customer browser. For more info on this, see here.

2.1.6. Payment received callback

When Payneteasy gets notified by processor that invoice is paid, it makes a callback to Merchant by using server_callback_url passed in the initial request. See Merchant Callbacks for more details what is passed with callback.

2.1.7. 3DS redirect

Upon completion of payment process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

3DS redirect Parameter Description
status See Status List for details.
orderid Order id assigned to the order by Payneteasy
merchant_order Merchant order id
client_orderid Merchant order id
error_message If status is declined or error this parameter contains the reason for decline or error details
control Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor Gate descriptor

If Merchant has passed server_callback_url in original Qiwi request Payneteasy will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters

2.1.8. Request authorization through control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

  • ENDPOINTID
  • client_orderid
  • minimal monetary units amount (i.e. cent, penny etc.)
  • currency
  • phone
  • merchant_control

A complete string example may look as follows:

5969200000RUB91212345673E8E45B5-2-42D8-6ECC-FBF6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for request authorization. For the above-mentioned example the control will take the following value:

7292b8d938beedc385320875928f39906e8b8d1f