Разработчикам

General Technical Details
Payment Process
Request for payment transaction creating /deposit/create
Payout Process
Request for payout transaction creating /deduce/create
Рефанды
Transaction Status Notification
Transaction Status Request
Balance request
Errors arising in operating with the system
Testing

General Technical Details

All the requests regarding Pay Key API should be sent to:

https://???.com/api
Lorem ipsum dolor sit amet consectetur adipisicing elit. Vero ipsam explicabo magni quasi rem. Saepe in velit provident, nulla enim, porro praesentium placeat vitae perspiciatis illum. Alias iusto autem necessitatibus.

All the requests should contain the Auth header with an authorization key that will be sent to Merchant, e.g.

POST /deposit/create HTTP/1.1
Host: paykey.space
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d

Pay Key API deals with JSON requests.

All the requests, excluding GET, should be signed by a secret key that will be also sent to Merchant. For signing you need to deliver the md5 hash from a request body with a secret a key concatenating. Then the delivered hash is used in the Sign header and sent together with the request.

The example of the hash calculation in PHP

$secret_key = '1dfcd12ba13fff487a84cf50d8099297';
$request = '{"test":"test"}';
$sign = md5($request . $secret_key);
//49e8dde596382693c52ccc3d722e5229

POST request will be written as

POST /deposit/create HTTP/1.1
Host: paykey.space
Accept: application/json
Content-Type: application/json
Auth: fcd8766d4fa5b4a5c7198b87a5d0921d
Sign: 49e8dde596382693c52ccc3d722e5229 … {"test":"test"}

Whereas Pay Key sends the requests to the Merchant system using the same rules and keys.

Payment Process

Please see below the scheme of the payment through Payment System by means of Pay Key API:

Client

Мерчант

Pay Key

Система платежей

1. Order creating and data entering

2. Creating and sending a deposit/create request

3. Request sending to the Payment system

4. Sending redirect parameters

6. User redirecting to payment page, data entering for payment

5. Response to the request with Pay Key transaction data and redirect parameters

8. User notification

7. User redirecting to Merchant site

Awaiting Pay Key notification

11. User notification, account crediting

10. Sending a payment status Notification with transaction data

9. Sending a payment status notification

A maximally general case is analyzed in this scheme. In different systems the schemes can differentiate. The information is thoroughly described in the section below.

In certain cases Merchant can charge fee from its Clients, in which case Pay Key system can reckon on it on its side and provide total amounts in the responses to the deposit/create, deduce/create requests, as well as return them by the notifications. For the purpose Merchant needs to provide the policies of fee accounting.

Merchant can also pay fee for its Client.

All the cases will be reviewed after the Section of Requests and Responses.

Request for payment transaction creating /deposit/create

The request is sent by POST to the address:

https://???.com/api

The request format is as follows:

Поле	Тип	Mandatory	Описание	Пример
amount	float(10,2)	Да	Transaction amount	10.00
currency	string(3)	Да	Transaction amount	RUB
payment_system	string	Да	Payment system name.	CardGate
transaction_id	string	Нет	Transaction number in the Merchant system.	123
note	string	Нет	Transaction description for the Merchant	Account deposit 321
system_fields	object	Нет	Container for additional fields of payment system.
url	object	Нет	Container for URL addresses transmitting.
url > callback_url	url	Нет	URL for transmitting notification of a payment to the Merchant system.	http://site.com/callback
url > fail_url	url	Нет	URL for user redirecting to the Merchant page in case of failure.	http://site.com/fail
url > pending_url	url	Нет	URL for user redirecting to the Merchant page in case of transaction nonfinal status.	http://site.com/pending
url > success_url	url	Нет	URL for user redirecting to the Merchant page in case of success.	http://site.com/success

The example of the request:

{
"transaction_id": "123",
"amount": "10.00",
"currency": "RUB",
"payment_system": "CardGate",
"url": {
"callback_url": "https://site.com/callback",
"fail_url": "https://site.com/fail",
"pending_url": "https://site.com/pending",
"success_url": "https://site.com/success" } }