2.3. Simple Qiwi integration

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.com/paynet/api/v2/simple-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.

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

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

* leading and trailing whitespace in input parameters will be omitted

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.

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;