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.eu/paynet/api/v2/qiwi-invoice/ENDPOINTID

for integration purposes use staging environment sandbox.payneteasy.eu instead of production gate.payneteasy.eu

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

Note

Request must have content-type=application/x-www-form-urlencoded.

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

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value

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. For amount 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)
• 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