2.3. Simple Qiwi integration¶

Simple Qiwi integration overview
Simple Qiwi API URL
Simple Qiwi Transaction Flow
A note about error handling
Simple Qiwi Request Parameters
Payment received callback
3DS redirect
Request authorization through signature parameter
An example
PHP example

2.3.1. Simple Qiwi integration overview ¶

We have a full-blown Qiwi integration built on a usual B2B requests with status polling etc. But sometimes its complexity and features are not needed. This is why a Simple Qiwi API is introduced. It requires from merchant to just make buyer post a form to our server, and the rest will be done by Payneteasy.

2.3.2. Simple 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/simple-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.

2.3.3. Simple Qiwi Transaction Flow ¶

Merchant displays a form to the customer which action attribute is set to Simple Qiwi API URL and which contains parameters according to Simple Qiwi Request Parameters
Customer submits that form and ends up on the Payneteasy server.
Payneteasy cooperates with Qiwi processor and redirects customer to it.
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.3.4. A note about error handling ¶

Unlike full-blown Qiwi Integration, in Simple Qiwi API that’s customer who actually makes a request to Payneteasy server. This means that if you calculate wrong signature or forget some mandatory parameter, customer will see a frustrating error. So please test your integration properly!

2.3.5. Simple Qiwi Request Parameters ¶

Note

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

Leading and trailing whitespace in input parameters will be omitted.

Qiwi Request Parameter	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
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
signature	40/String	Signature generated by HMAC-SHA1. See OAuth.	Mandatory

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

Note

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

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.3.8. Request authorization through signature parameter ¶

The signature is used to ensure that order data will not be altered by someone while transferred. Signature is computed like this:

All parameters to be posted via form to Simple Qiwi API URL are sorted by keys in lexicographical order
Their values are glued together in that order using semicolon as a separator – this gives you a base string
Base string is converted to bytes using utf-8 encoding which gives you a binary base string
Merchant control is converted to byte string using unhex transformation – this gives you a binary merchant control
The binary base string is fed to the HMAC_SHA1 algorithm using the binary merchant control as a key
Result of HMAC_SHA1 is converted to hex string – this is the final signature
Warning! Please note that ALL parameters which will be posted will be used to compute the signature! That means, for instance, that you must not specify name attribute on your submit input control, so its value does not get posted too.

2.3.9. An example ¶

Let’s assume you have the following form data array:

Array
(
 [version] => 21
 [order_desc] => order for number 1363332564
 [amount] => 0.1
 [currency] => USD
 [phone] => 9151245661
 [redirect_url] => http://localhost/dump_vars.php
 [client_orderid] => 1363332564
 [server_callback_url] => http://localhost/
)

Base string will look like this:

0.1;1363332564;USD;order for number 1363332564;9151245661;http://localhost/dump_vars.php;http://localhost/;21

Assuming merchant key to be 874A3BBC-4B9F-D581-1234-111111111111.

Final signature:

1079c0618e138b4feb4d75e796517695a1444766

2.3.10. PHP example ¶

Here is an example of how this may be done in PHP (assuming data to be posted via form is contained in the associative array called $ar):

ksort($ar);
$base = implode(';', array_values($ar));
$base = mb_convert_encoding($base, 'utf-8'); // only needed if your data is not already in utf-8
$control_key = str_replace('-', '', $control_key);
$signature = hash_hmac('sha1', $base, pack('H*', $control_key));
$ar['signature'] = $signature;

Quick search

2.3. Simple Qiwi integration¶