Registration

For a start, pass the registration at https://cabinet.billline.net/register

After registration, you will get access to the user’s personal area.

For creation of a merchant you should go to the “Merchants” tab (on the sidebar) and click on “+” (Fig. 1).

Fig. 1

When registering a new merchant, fill in the fields:

1. Name of a merchant

Specify the merchant name

2. Link to the resource

You should enter URL of your resource

3. Secret key of a merchant

Click the “Generate” button for automatic generation of the key

Filling in the following fields is related to deposit

4. URL address callback in the form

Choosing “YES”, you confirm your consent to URL address callback to the payment form (where the customer will be redirected after the payment is made – success_url after successful acceptance of payment for processing, fail_url – in case of payment rejection).

If you leave the value “NO”, the address will be taken from the merchant’s default settings (process_url).

5. URL address of the payment processor on the side of the store (process_url)

Enter the URL address of the payment processor on the side of the store, and also specify the type of query that shall be sent to the specified address.

6. URL address of redirection in case of successful transaction (success_url)

Enter the URL address of the payer’s redirection in case of successful transaction, and also specify the type of query that shall be sent to the specified address.

7. URL address of redirection in case of error of transaction (success_url)

Enter the URL address of the payer’s redirection in case of error of transaction, and also specify the type of query that shall be sent to the specified address.

Filling in the following fields is related to withdrawal

8. Receiving a callback response with the results of withdrawal

Choosing “YES”, you confirm the receipt of callback queries with the results of withdrawal. Otherwise, the result shall be received independently (by sending a query for payment status).

9. URL address of the callback response processor (withdrawal_url)

In this field, you shall specify the URL to which a response with the result of withdrawal and the method will be sent by which the data will be transmitted (GET or POST). If these actions are not performed, then the notification of change in the transaction status will not be sent.

10. Return of the recipient’s card mask in the callback response

Choosing “YES”, you agree to receive the recipient’s card mask in callback (in the format 123412XXXXXX4321). Provided that callback responses are included.

11. Access to API methods “Payout Send” and “Payout Status”

In this setting, you can restrict the IP addresses from which it will be allowed to receive a query for withdrawal.

We recommend to restrict the access, this will protect you additionally.

For activation of the merchant, contact the support service support@billline.net

Also, after activation of the merchant, the support service will report the base URL for API queries.

Electronic Signature

Electronic Signature in Queries

1. Each of the API methods specifies which fields are used to generate the signature, as well as a hashing method (MD5 or SHA256).

2. After having selected the required fields, you shall to sort them alphabetically (in ascending order).

3. The secret key of the merchant is added at the end.

4. Catenation of all fields is performed through the “:” symbol without their names.

5. The received string is hashed (using MD5 or SHA256 method) and its bytecode is encoded in Base64:

sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'), true))

or

sign = Base64(SHA256 (Implode(Sort(Params) + SecretKey, ':'), true))

6. Example of the signature for Payout Send query:

$data = ['merchant' => 'M1VJDHSI6DYXS',
    'method' => 1,
    'payout_id' => '000002',
    'account' => '5300111122223333',
    'amount' => 1.19,
    'currency' => 'UAH'];
$dataSet = $data;
ksort($dataSet, SORT_STRING);
array_push($dataSet, 'SecRetKey0123’);
$signString = implode(':', $dataSet);
$calc_sign = base64_encode(md5($signString, true));
$data['sign'] = $calc_sign;

Electronic Signature in Callback

1. All fields of the form with the “co_” prefix are sorted alphabetically.

2. The secret key of the merchant is added at the end.

3. Catenation of all fields is performed through the “:” symbol without their names.

4. Example of the string for data signing for Payout Send query:

16:UAH:2019-02-19 19:12:04:2019-02-19 19:12:11:success:1:M1VJDHSI6DYXS:20:34:15.76:SecretKey

5. The received string is hashed using MD5 method, and its bytecode is encoded in Base64:

co_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'), true))

6. Example of data signing in the response for Payout Send query:

$data = ['co_inv_id' => '1111111',
    'co_inv_crt' => '2021-02-16 19:12:04',
    'co_inv_prc' => '2021-02-16 19:12:11',
    'co_inv_st' => 'Success',
    'co_payout_id' => '000002',
    'co_merchant_uuid' => 'M1VJDHSI6DYXS'];
$dataSet = $data;
ksort($dataSet, SORT_STRING);
array_push($dataSet, 'SecRetKey0123’);
$signString = implode(':', $dataSet);
$calc_sign = base64_encode(md5($signString, true));
$data['sign'] = $calc_sign;

Verification of Electronic Signature

Verification of the electronic signature is performed upon receipt of the query. We also highly recommend to implement verification on the side of the merchant.

Verification of the electronic signature:

$secret_key = 'SecretKey'; // secret key of the merchant
$dataSet = json_decode($response, TRUE);
$sign = $dataSet['sign'];
unset($dataSet['sign']);
ksort($dataSet, SORT_STRING);
array_push($dataSet, $secret_key);
$signString = implode(':', $dataSet);
$calc_sign = base64_encode(md5($signString, true));

if ($sign != $calc_sign) {
    // Sign error
    echo ('Sign error');
    } else {
    echo 'Sign Ok';
    }

Callbacks

The callback mechanism is used to notify the merchant that the transaction has received a final status (for example, from “Pending” to “Success”).

The callback is sent:

  • In case of finalization of the deposit transaction to the URL address of the payment processor on the side of the store (process_url);
  • In case of finalization of the withdrawal transaction to the URL address of the callback response processor (withdrawal_url).

In response to the received packet, the store server shall respond with two English letters “OK”.

If it was not possible to send a query to callback_url, or the response was received other than “OK”, the repeated attempts of callback delivery will be performed until the “OK” response is received.

In total, 20 attempts of callback delivery is performed. The interval between callback sending is:

  • from 1 to 10 – 5 min.;
  • from 11 to 20 – 60 min.

Callback in Case of Successful Replenishment (iframe and host-2-host)

If the payment is successful, the payment data are sent to the “process_url” store server using the POST method:

Callback contains the fields:

“co_inv_id” – unique number of transaction;

“co_inv_crt” – Transaction creation date and time;

“co_inv_prc” – Date and time of transaction performance;

“co_inv_st” – Status of successful performance (“Success”);

“co_order_no” – transaction number in the system of the merchant (transferred by the merchant when making the payment);

“co_amount” – transaction amount in the currency, separator character is a point “.”;

“co_to_wlt” – amount of crediting the account of the merchant (less commission);

“co_cur” – transaction currency;

“co_merchant_id” – unique number of the merchant;

“co_merchant_uuid” – unique ID of the merchant;

“co_sign” – electronic signature with the merchant’s key (described in more details in the section “Electronic Signature in Callback”);

“co_card_number” – transfer of the card mask. This field is not present in the response by default. In order to receive it in response, you shall set the value “YES” in the field “Cardmask in callback” in the merchant’s settings.

Example:

{
    "co_inv_id" : "1111111",
    "co_inv_crt" : "2019-02-19 19:12:04",
    "co_inv_prc" : "2019-02-19 19:12:11",
    "co_inv_st" : "success",
    "co_order_no" : "0001",
    "co_amount" : "16",
    "co_to_wlt" : "15.95",
    "co_cur" : "UAH",
    "co_merchant_id" : "1",
    "co_merchant_uuid" : "M1VJDHSI6DYXS",
    "co_sign" : "pQQgUBfjz+XxRSpwo5srmw=="
}

In response to the received packet, the merchant’s server shall respond with two English letters “OK”. 

Callback in Case of Payment Rejection (iframe and host-2-host)

If the payment is rejected, the missent payment data are sent to the “process_url” store server using the POST method:

“co_inv_id” – unique number of transaction;

“co_inv_crt” – Payment creation date and time;

“co_inv_prc” – Date and time of payment making;

“co_inv_st” – status of payment making (“Fail”);

“co_order_no” – transaction number in the system of the merchant (transferred by the merchant when making the payment);

“co_merchant_id” – unique number of the merchant;

“co_merchant_uuid” – unique ID of the merchant;

“co_sign” – electronic signature with the merchant’s key (described in more details in the section “Electronic Signature in Callback”).

Example:

{
    "co_inv_id" : "1111111",
    "co_inv_crt" : "2019-02-19 19:12:04",
    "co_inv_prc" : "2019-02-19 19:12:11",
    "co_inv_st" : " fail",
    "co_order_no" : "0001",
    "co_merchant_id" : "1",
    "co_merchant_uuid" : "M1VJDHSI6DYXS",
    "co_sign" : "pQQgUBfjz+XxRSpwo5srmw=="
}

In response to the received packet, the merchant’s server shall respond with two English letters “OK”.

Callback in Case of Payout

The notification will be sent if the transaction status is changed (for example, from “Pending” to “Success”).

The data is transferred to the URL address of the callback response processor (specified in the merchant’s settings) using the GET or POST method.

Callback in case of payout contains the fields:

“co_inv_id” – unique number of transaction;

“co_inv_crt” – Payment creation date and time;

“co_inv_prc” – Date and time of payment making;

“co_inv_st” – status of payment making (”Success” or “Fail”);

“co_payout_id” – payment number in the merchant’s system (payout number);

“co_merchant_uuid” – unique ID of the merchant;

“co_sign” – electronic signature with the merchant’s key (described in more details in the section “Electronic Signature in Callback”).

Example of Callback in case of payout:

Array
(
    [co_inv_id] => 1111111
    [co_inv_crt] => 2021-02-16 19:12:04
    [co_inv_prc] => 2021-02-16 19:12:11
    [co_inv_st] => Success
    [co_payout_id] => 000002
    [co_merchant_uuid] => M1VJDHSI6DYXS
    [co_sign] => XXXXXXXXXXXXXXXXXX
)

API Methods

List of API methods:

/payment/form – Query for Deposit (iframe)

/api/host2host – Query for Deposit (host-2-host)

/payment/status – Query for Payment Status (Deposit)

/merchant/api/payout_send – Query for Payout

/merchant/api/payout_status – Query for Payment Status (Payout)

/payment/balance – Query for Balance

/api/payment-list – Query for the List of Payments

Deposit (iframe)

Initial Query

In case of the query for a payment form, the data is sent to https://<provided url>/payment/form using the POST method.

The query contains the fields:

“merchant” – unique ID of the merchant;

“order” – transaction number in the system of the merchant;

“amount” – transaction amount in the currency, separator character is a point “.”;

“currency” – transaction currency, may take values UAH, RUB, USD and EUR;

“item_name” – name of the merchandise;

“first_name” – customer’s name. Maximum length is 30 characters;

“last_name” – customer’s surname;

“country” – customer’s country in the ISO 3166-1 alpha-2 format;

“ip” – IP address of the customer;

“custom” – for additional information about the customer;

“lang” – language (added on 07.26.2021.) In which the payment form will be displayed:

en – English

ru – Russian

ua – Ukrainian

If you do not send the “lang” field, the payment form in Russian will be displayed by default.

The fields “merchant”, “order”, “amount”, “currency” are mandatory.

Filling in the rest of the fields is optional, they can be used for additional identification of the customer.

The fields “process_url”, “success_url”, “fail_url” (where the customer will be redirected after the payment is made) shall not be transferred. This data is taken automatically from the merchant’s settings in the personal area.

In some cases, the “last_4” field is used in the query, in which the last 4 digits of the card number are transmitted. 

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "order" : "0001",
    "amount" : "16",
    "currency" : "UAH",
    "item_name" : "Samsung TV",
    "first_name" : "IVAN",
    "last_name" : "IVANOV",
    "country" : "UA",
    "ip" : "212.10.20.75",
    "custom" : "",
    "lang" : "en"
}

Redirection of the Customer after Making a Payment

Attention! Direction of the buyer to success_urlor fail_urlis only informational and CANNOT confirm the success or rejection of deposit!

After making a payment, the customer is redirected to “success_url” or “fail_url”.

The data is transferred using the POST method.

The response contains the fields:

“order_no” – transaction number in the system of the merchant (the same as in the query “order”);

“amount” – transaction amount in the currency, separator character is a point “.”;

“currency” – transaction currency (in which the invoice was drawn);

“item_name” – name of the merchandise (if it was transferred);

“co_inv_id” – unique number of transaction;

“co_inv_st” – transaction status in the payment system (Success or Canceled).

Example of the response in case of successful acceptance of payment for processing:

{
    "order_no" : "0001",
    "amount" : "16",
    "currency_code" : "UAH",
    "item_name" : "Samsung TV",
    "co_inv_id" : "1111111",
    "co_inv_st" : "success"
}

Example of the response in case of payment cancellation:

{
    "order_no" : "0001",
    "amount" : "16",
    "currency_code" : "UAH",
    "item_name" : "Samsung TV",
    "co_inv_id" : "1111111",
    "co_inv_st" : "canceled"
}

Final Status (Callback)

The callback mechanism is used to notify the merchant that the transaction has received a final status (for example, from “Pending” to “Success”).

It is described in detail in the Callbacks section.

Deposit (host-2-host)

According to the rules of Mastercard and Visa payment systems, the PCI DSS certificate (of the appropriate level) is mandatory, as the customer enters the card details on the merchant’s website.

Initial Query

In case of the initial query, the data is sent to “https://<provided url>/api/host2host” using the POST method.

The query contains the fields:

“type” – transaction type (payment);

“merchant” – unique ID of the merchant;

“order” – transaction number in the system of the merchant;

“amount” – transaction amount in the currency, separator character is a point “.”;

“currency” – transaction currency, may take values UAH, RUB, USD and EUR;

“card_num” – card number;

“card_exp_month” – card expiration month;

“card_exp_year” – card expiration year;

“card_cvv” – cvv of the card;

“process_url” – URL for sending of the summary status of transaction

“item_name” – name of the merchandise (the field is optional);

“first_name” – card holder name (the field is obligatory for more than 30 thousand hryvnia);

“last_name” – card holder surname (the field is obligatory for more than 30 thousand hryvnia);

“sign” – electronic signature with the merchant’s key. The fields “type”, “merchant”, “order”, “amount”, “currency”, “card_num”, “card_exp_month”, “card_exp_year”, “card_cvv” are used. It is hashed using the SHA256 method. (described in more details in the section “Electronic Signature in Queries”)

“browser” – an array in which data about the customer’s browser is transmitted, namely:

    “accept_header”

    “color_depth”

    “ip”

    “language”

    “screen_height”

    “screen_width”

    “time_different”

    “user_agent”

    “java_enabled”

    “window_width”

    “window_height”

Example of the PHP query:

$url = "https://<provided url>/api/host2host";
$merchant = "M1VJDHSI6DYXS";
$signature = "XXXXXXXXXXXXXXXXXX";
$order_id = "0001";
$data = [
    "type" => "payment",
    "merchant" => $merchant,
    "order" => $order_id,
    "amount" => "10.99",
    "currency" => "UAH", 
    "card_num" => "5300111122223333",
    "card_exp_month" => "01",
    "card_exp_year" => "25",
    "card_cvv" => "111",
    "callback_url" => "https://test.com/api/callback_url",
    "item_name" => "Samsung TV",
    "first_name" => "IVAN",
    "last_name" => "IVANOV",
    "browser" => [
    "accept_header" => "...",
    "color_depth" => "...",
    "ip" => "...",
    "languager" => "...",
    "screen_height" => "...",
    "screen_width" => "...",
    "time_different" => "...",
    "user_agent" => "...",
    "java_enabled" => "...",
    "window_width" => "...",
    "window_height" => "..."
    ],
];
$dataSign = array_filter(
    $data,
    fn ($key) => in_array($key, [ 'type', 'merchant', 'order', 'amount', 'currency', 'card_num', 'card_exp_month', 'card_exp_year', 'card_cvv' ]),
    ARRAY_FILTER_USE_KEY
);
/*
simplified version: 
$dataSign = [ $data['type'], $data['merchant'], $data['order'], $data['amount'], $data['currency'], $data['card_num'], $data['card_exp_month'], $data['card_exp_year'], $data['card_cvv'] ];
*/
ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(':', $dataSign);
$sign = base64_encode(hash('sha256', $signString, true));
$data['sign'] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($request))
);
$result = curl_exec($ch);

If the data is successfully received (for further payment), the response contains the fields:

“status” – transaction status (3ds);

“merchant” – unique ID of the merchant;

“order” – transaction number in the system of the merchant (the same as in the query);

“uuid” – unique ID of the transaction, use it for searching and, if necessary, contact technical support;

“co_inv_id” – unique number of transaction;

“d3_acs_url” – link to the 3DS page, where the customer shall be redirected;

“d3_pareq” – data for passing;

“d3_md” – data for passing.

Example of the response:

{
    "status": "3ds",
    "merchant": "M1VJDHSI6DYXS",
    "order": "0001",
    "uuid": "ABC123abc123",
    "co_inv_id": 1111111,
    "d3_acs_url": "https://3ds.bank.ua",
    "d3_pareq": "eJxVUt...tuwjAM/RX==",
    "d3_md": "1:809b...82316eb"
}

If the payment is canceled, the response contains the fields:

“status” – transaction status (error);

“code” – error code;

“description” – error description.

Example of the response:

{
    "status": "error",
    "code": "10",
    "description": "The order is already in the system. Request a status."
}

Redirection of the Customer to the 3DS Form

In case of positive response, the merchant shall redirect the customer to the 3DS form. For this, use the parameters from the response at the initial query.

<form name="MPIform" action="{{ d3_acs_url }}" method="POST" target="_blank">
    <input type="text" name="PaReq" value="{{ d3_pareq }}" />
    <input type="text" name="MD" value="{{ d3_md }}" />
    <input type="text" name="TermUrl" value="{{ URL }}" />
    <button type="submit">Send</button>
</form>

Totals Query

The data is sent to “https://<provided url>/api/host2host” using the POST method.

*Pay attention! Do not confuse d3_pares and d3_pareq:

you receive d3_pareq in response to the initial query and send to the 3DS form;

you receive d3_pares from the 3DS form and send in the totals query.

The query contains the fields:

“type” – type (3ds);

“merchant” – unique ID of the merchant;

“uuid” – unique ID of the transaction (parameter that you receive in the response at the initial query);

“order” – transaction number in the system of the merchant (the same as in the initial query);

“d3_pares” – you receive in the response from the 3DS form;

“d3_md” – data for passing (you receive in the response at the initial query);

“sign” – electronic signature with the merchant’s key. The fields “type”, “merchant”, “order”, “uuid”, “d3_md” are used. It is hashed using the SHA256 method. (described in more details in the section “Electronic Signature in Queries”).

Example:

$data = [
    "type" => "3ds",
    "merchant" => $merchant ,
    "uuid" => "BILLLINE ID",
    "order" => "Ваш ID который указывали ранее",
    "d3_pares" => $d3_pares,
    "d3_md" => $d3_md,
];
$dataSign = array_filter(
    $data,
    fn ($key) => in_array($key, [ 'type', 'merchant', 'order', 'uuid', 'd3_md' ]),
    ARRAY_FILTER_USE_KEY
); 

/*
simplified version: 
$dataSign = [ $data['type'], $data['merchant'], $data['order'], $data[' uuid '], $data[d3_md'] ];
*/

$dataSign = [ $data['type'], $data['merchant'], $data['order'], $data[' uuid '], $data[d3_md'] ];
ksort($dataSign, SORT_STRING);
array_push($dataSign, $signature);
$signString = implode(':', $dataSign);
$sign = base64_encode(hash('sha256', $signString, true));
$data['sign'] = $sign;
$request = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($request))
);
$result = curl_exec($ch);

If the query is successfully processed, the response contains the fields:

“status” – payment status (success);

“merchant” – unique ID of the merchant;

“uuid” – unique ID of the transaction, use it for searching and, if necessary, contact technical support;

“order” – transaction number in the system of the merchant (the same as in the query);

Example of the response:

{
    "type" : "3ds",
    "merchant" : "M1VJDHSI6DYXS",
    "uuid" : "ABC123abc123",
    "order" : "0001",
    "d3_pares" : "eJzVmNmS...ovrSsTczhh==",
    "d3_md" : "1:809b...82316eb",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

In case of the payment error, the response contains the fields:

“status” – payment status (Error);

“code” – error code;

“description” – error description.

Example of the response:

{
    "error": "error",
    "code": "2",
    "description": "Incorrect request details"
}

Final Status (Callback)

The callback mechanism is used to notify the merchant that the transaction has received a final status (for example, from “Pending” to “Success”).

It is described in detail in the Callbacks section.

Query for Payment Status (Deposit)

The query for payment status is sent to URL https://<provided url /payment/status, POST or GET data transfer method.

The query contains the fields:

“merchant” – unique ID of the merchant;

“order” – transaction number in the system of the merchant;

“co_inv_id” – unique number of transaction (the number is transferred after payment processing to the merchant’s Process URL);

“sign” – electronic signature with the merchant’s key. The fields “merchant”, “order”, “co_inv_id” are used. It is hashed using the MD5 method. (described in more details in the section “Electronic Signature in Queries”).

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "order" : "0001",
    "co_inv_id" : "1111111",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

In response to the query the data is returned in the JSON format:

“status” – transaction status:

    Success – the payment is successfully effected (final status)

    Pending – the payment is new or is in the queue for processing

    Fail – the payment is canceled (final status)

    Refund – the payment was refunded (final status)

    Error – error of data received (signature in the response is empty “sign” = “”)

“order” – transaction number in the system of the merchant;

“description” – status description;

“card_number” – card mask (in the format NNNNNN******NNNN, where N – digit);

“sign” – electronic signature with the merchant’s key.

Example of the response – Success status:

{
    "status" : "success",
    "order" : "0001",
    "description" : "Merchant payment success",
    "card_number" : "530011******3333",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

{
    "status" : "Error",
    "order" : "0001",
    "description" : "Merchant payment not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Payouts to the Card

For correct setting of payouts, go to “Personal Account” – “Editing of a merchant”.

The detailed description of these settings can be found in the “Registration” section (paragraphs 8-11).

Query for Payout

In case of the query for payout, the data is sent to “https://<provided url>/merchant/api/payout_send” using the POST method.

The query contains the fields:

“merchant” – unique ID of the merchant;

“method” – payout method, integer value:

    1 – Visa/Mastercard UAH

    3 – Visa/Mastercard RUB

    8 – Mastercard USD

    9 – Mastercard EUR

“payout_id” – outgoing payment number in the merchant’s system;

“account” – prepaid card number (Visa or Mastercard);

“amount” – transaction amount in the currency, separator character is a point “.”;

“currency” – transaction currency, shall correspond to the field “method”:

    “UAH” for method 1

    “RUB” for method 3

    “USD” for method 8

    “EUR” for method 9

“sign” – electronic signature with the merchant’s key. The fields “merchant”, “method”, “payout_id”, “account”, “amount”, “currency” are used. It is hashed using the MD5 method (described in more details in the section “Electronic Signature in Queries”).

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "method" : 1,
    "payout_id" : "000002",   
    "account" : "5300111122223333", 
    "amount" : "102.81",
    "currency" : "UAH",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

The response contains the fields:

“status” – transaction status:

    Success – the payment is successfully effected (final status)

    Pending – The payment is new or is in the queue for processing. The Pending status requires an additional query (it is described in detail in the section “Query for Payment Status (Payout)”).

    Blocked – The payment is canceled (final status)

    Error – error of data received. The response contains a signature with an empty key (the status is not final and constitutes grounds for finding out the reason of this status)

“code” – code of the transaction status;

“payout_id” – outgoing payment number in the merchant’s system;

“description” – status description;

“sign” – electronic signature with the merchant’s key.

Example of the response – Success status:

{
    "status" : "Success",
    "code" : "0",
    "payout_id" : 000002,
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Pending status:

{
    "status": "Pending",
    "code": "40",
    "payout_id": 000002,
    "description": "Payment in order",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

{
    "status": "Error",
    "code": "99",
    "payout_id": "",
    "description": "Sign error",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Final Status (Callback)

The callback mechanism is used to notify the merchant that the transaction has received a final status (for example, from “Pending” to “Success”).

It is described in detail in the Callbacks section.

Query for Payment Status (Payout)

The query for payment status is sent to URL https://<provided url / merchant/api/payout_status, POST data transfer method.

The query contains the fields:

“merchant” – unique ID of the merchant;

“payout_id” – outgoing payment number in the merchant’s system;

“sign” – electronic signature with the merchant’s key. The fields “merchant” and “payout_id” are used. It is hashed using the MD5 method (described in more details in the section “Electronic Signature in Queries”).

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "payout_id" : "000002",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

In response to the query the data is returned in the JSON format:

“status” – transaction status:

    Success – the payment is successfully effected (final status)

    Pending – the payment is new or is in the queue for processing

    Blocked – the payment is canceled (final status)

    Error – error of data received (signature in the response is empty “sign” = “”)

“payout_id” – outgoing payment number in the merchant’s system;

“code” – code of the payment status;

“description” – status description;

“sign” – electronic signature with the merchant’s key.

Example of the response – Success status:

{
    "status" : "Success",
    "payout_id" : 000002,
    "code" : "0",
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

{
    "status" : "Error",
    "code" : "8",
    "payout_id" : "",
    "description" : "Transaction not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Blocked status:

{
    "status" : "Blocked",
    "payout_id" : 000002,
    "code" : "80",
    "description" : "Payment error. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Query for Balance

The query for balance is sent to URL https://<provided url>/payment/balance, POST data transfer method.

The query contains the fields:

“merchant” – unique ID of the merchant;

“currency” – requested currency (UAH, RUB, USD or EUR);

“sign” – electronic signature with the merchant’s key. The fields “merchant”, “currency” are used. It is hashed using MD5 method (described in more details in the section “Electronic Signature in Queries”).

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "currency" : "UAH",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

The response contains the fields:

“status” – query status:

    Success – successful query

    Error – error of data received (if the merchant is not found, the signature in the response is not transferred)

“currency” – requested currency (UAH, RUB, USD or EUR);

“balance” – available currency amount with two decimal places, separator character is a point (for example – 212.07);

“description” – description (”Wallet balance”);

“sign” – electronic signature with the merchant’s key.

Example of the response – Success status:

{
    "status": "Success",
    "currency": "UAH",
    "balance": 212.07,
    "description": "Wallet balance",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

{
    "status": "Error",
    "merchant": "M1VJDHSI6DYXS",
    "description": "Merchant not found or not Approved"
}

Query for the List of Payments

The queries for the list of payments are processed not more than one per minute.

The maximum number of transactions in the response is 10,000.

The query for the list of payments is sent to URL https://<provided url>/api/payment-list, data transfer method may be POST or GET.

The query contains the fields:

“merchant” – unique ID of the merchant;

“currency” – requested currency (UAH, RUB, USD or EUR);

“order” – the number of the transaction in the merchant’s system, from which the selection begins in the specified period (if 0 is transferred, then all transactions are returned);

“start_date” – date and time of the beginning of the period in the format YYYY-MM-DD HH:ii:ss;

“finish_date” – date and time of the end of the period in the format YYYY-MM-DD HH:ii:ss;

“status” – status of payments to be selected (all, success, pending, blocked, refund);

“type” – transaction type (withdrawal or deposit);

“sign” –  electronic signature with the merchant’s key. The fields “merchant”, “currency”, “order”, “start_date”, “finish_date”, “status”, “type” are used. It is hashed using MD5 method (described in more details in the section “Electronic Signature in Queries”).

Examples of the query:

{
    "merchant" : "M1VJDHSI6DYXS",
    "currency" : "UAH",
    "order" : "0",
    "start_date" : "2021-02-09 00:00:00",
    "finish_date" : "2021-02-11 16:59:59",
    "status" : "all",
    "type" : "deposit",
    "sign" : "XXXXXXXXXXXXXXXXXX" 
}

The response contains the fields:

“id” –  unique number of transaction;

“uid” – unique ID of the transaction (the same as “uuid”);

“order_id” – transaction number in the system of the merchant;

“subtotal” – amount charged:

    In case of “Deposit” – to the merchant’s balance

    In case of “Withdrawal” – to the card

“fee_percentage” – deducted fee (if the type of fee is a per cent):

    In case of “Deposit” deducted from “total”

    In case of  “Withdrawal” accrued to “subtotal”

“fee_fixed” – deducted fee (if the type of fee is fixed):

    In case of “Deposit” deducted from “total”

    In case of  “Withdrawal” accrued to “subtotal”

“total” – total amount of transaction:

    In case of “Deposit” – deposit amount without charging a fee

    In case of “Withdrawal” – payout amount with accrued fee

“type” –  transaction type (withdrawal or deposit);

“status” – transaction status (Success, Pending, Blocked, Refund);

“created_at” –  transaction creation date and time;

“updated_ad” – date and time of transaction performance.

Example of the response – Success status:


    {
        "id" : 11114,
        "uid" : "ABA4OD7X73L4Q",
        "order_id" : "0083",
        "subtotal" : 0.9,
        "fee_percentage" : 0,
        "fee_fixed" : 0.1,
        "total" : 1,
        "currency" : "UAH",
        "type" : "Deposit",
        "status" : "Success",
        "created_at" : "2021-02-10 09:34:57",
        "updated_ad" : "2021-02-10 09:37:40"
    }

Example of the response – Blocked status:

    {
        "id" : 11115,
        "uid" : "XTJTEZXMJAUMT",
        "order_id" : "0084",
        "subtotal" : 0.9,
        "fee_percentage" : 0,
        "fee_fixed" : 0.1,
        "total" : 1,
        "currency" : "UAH",
        "type" : "Deposit",
        "status" : "Blocked",
        "created_at" : "2021-02-10 10:22:32",
        "updated_ad" : "2021-02-10 10:24:17"
    }

Example of the response – Error status:

{
    "status": "Error",
    "description": "Please send one request per minute"
}

Status codes

Status codeStatusFinalDescription
0SuccessYesPayout successful
2ErrorNoInput data error
3ErrorNoPayment method blocked
4ErrorNoMarchant blocked
5ErrorNoPayout currency error
6ErrorNoMerchant account blocked
7ErrorNoThe amount exceeds the balance
8ErrorNoTransaction ID not found
10ErrorNoRepeated withdrawal request, transaction status request required
40PendingNoTransaction in processing
80BlockedYesRefused to pay
99ErrorNoSignature error in request
100ErrorNoThe error is not documented