API - billline.net
API Documentation is available on screens with a resolution higher than 1024 px in width

To the Home Page

Sign up

Sign up at https://billline.net/connect-en/#form-connect to start

After signing up you will get access to the your account

Create a merchant: go to the "Merchants" tab (on the sidebar) and click on “+” (Fig. 1).

Sign up - billline.net

Fig. 1

Fill in the fields, when you're registering a new merchant:

1. Merchant name

Type the merchant name

2. Link to the resource

You should enter URL of your resource

3. Secret key of a merchant

Click "Generate" button for automatic key generation

Filling in the following fields is related to payment acceptance (deposit)

4. URL transition in the form

By choosing “YES”, you confirm your consent to URL address transition 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 "NO" option, 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 payment processor's URL address from the store. Also. you need to specify what type of request shall be sent to the specified address.

6. Redirection URL 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 request shall be sent to the specified address.

7. Redirection URL 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 request shall be sent to the specified address.

Filling in the following fields is related to payouts (Withdrawal)

8. Receiving a callback response with the results of withdrawal

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

9. URL of the callback response processor (withdrawal_url)

Here you must 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”

Here you can restrict the IP addresses from which it will be allowed to receive a request 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, our support service will report the base URL for API queries.

Digital Signature

Digital Signature in requests

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

2. After you select the required fields, you must sort them alphabetically (in ascending order).

3. Secret merchant key is added at the end.

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

5. The line you received 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))

Example of the signature for Payout Send request:

Copy
Expand all
Collapse all
$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;

Digital Signature in Callback

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

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

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

4. Example of the string for data signing for Payout Send request: 16:UAH:2019-02-19 19:12:04:2019-02-19 19:12:11:success:1:M1VJDHSI6DYXS:20:34:15.76:SecretKey

5. The line you received is hashed using MD5 method, and its bytecode is encoded in Base64: co_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'), true))

Example of data signing in the response for Payout Send request:

Copy
Expand all
Collapse all
$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;

Digital signature verification

Digital signature verification is performed after the request is received. We highly recommend to implement an additional verification on the merchant's side.

Digital signature verification

Copy
Expand all
Collapse all
$secret_key = 'SecretKey'; // merchant's secret key
$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 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 package, the store server shall respond with two English letters “OK”.

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

There are 20 callback attempts delivery performed in total. The interval between callback sending is:

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

Callback in "payment successful" case (iframe and host-2-host)

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

Callback contains the fields:

  • co_inv_id

    unique transaction number;

  • co_inv_crt

    transaction creation date and time;

  • co_inv_prc

    transaction processing date and time;

  • co_inv_st

    payment processing status (“Success”);

  • co_order_no

    transaction number in the merchant system (transferred by the merchant when payment is making);

  • co_amount

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

  • co_to_wlt

    amount of crediting the merchant account (minus fee);

  • co_cur

    transaction currency;

  • co_merchant_id

    unique merchant number;

  • co_merchant_uuid

    unique merchant ID;

  • co_sign

    digital signature with the merchant’s key (for more details read the “Digital signature in callback” section);

  • 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 must set “YES” in the field “Cardmask in callback” in the merchant’s settings.

If an internal conversion is performed, additional fields may be present in the callback:

  • co_base_amount

    the base amount received in the request;

  • co_base_currency

    the base currency used in the payment request;

  • co_rate

    conversion rate;

During the converting, the co_cu field will include the processing currency, and the co_amount and co_to_wlt fields will include the amounts in the processing currency.

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

Example:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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=="
}

Callback in "payment rejected" case (iframe and host-2-host)

If the payment is failed, the missent payment data will be sent to the “process_url” store server using the POST method:

  • co_inv_id

    unique transaction number;

  • co_inv_crt

    transaction creation date and time;

  • co_inv_prc

    transaction processing date and time;

  • co_inv_st

    payment processing status (“Fail”);

  • co_order_no

    transaction number in the merchant system (transferred by the merchant when payment is making);

  • co_merchant_id

    unique merchant number;

  • co_merchant_uuid

    unique merchant ID;

  • co_sign

    digital signature with the merchant’s key (for more details read the “Digital signature in callback” section);

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

Example:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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=="
}

Callback in payout case

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

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

Callback in payout case contains certain fields:

  • co_inv_id

    unique transaction number;

  • co_inv_crt

    transaction creation date and time;

  • co_inv_prc

    transaction processing date and time;

  • co_inv_st

    payment processing status ("Success" or "Fail");

  • co_payout_id

    payment number in the merchant’s system (payout number);

  • co_merchant_uuid

    unique merchant ID;

  • co_sign

    digital signature with the merchant’s key (for more details read the “Digital signature in callback” section);

Example of callback in payout case:

Copy
Expand all
Collapse all
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

    payment request (iframe)

  • /api/host2host

    payment request (host-2-host)

  • /payment/status

    payment status request (Deposit)

  • /merchant/api/​payout_send

    payout request

  • /merchant/api/​payout_status

    payment status request (Payout)

  • /payment/balance

    balance request

  • /api/payment-list

    payments list request

Deposit (iframe)

Initial request

The request contains certain fields:

  • merchant

    unique merchant ID;

  • order

    transaction number in the merchant system;

  • amount

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

  • currency

    transaction currency, may take UAH, USD, EUR, KZT, BRL and AZN;

  • item_name

    goods name;

  • first_name

    customer’s name. Maximum length is 30 characters (Only latin chars are available);

  • last_name

    customer’s surname (Only latin chars are available);

  • user_id

    client identifier in the merchant's system (the field is not required);

  • payment_url

    url address of the site in whose favor the payment is made;

  • country

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

  • ip

    customer's IP address;

  • custom

    for additional information about the customer;

  • email

    customer's e-mail

  • phone

    customer's phone number

  • address

    customer's address

  • city

    customer's city

  • post_code

    customer's post code

  • region

    customer's region

  • lang

    language (added on 07.26.2021) in which the payment form will be displayed:

    en — English

    ua — Ukrainian

  • cpf

    Client's CPF (Only for PIX payment method)

The fields "process_url", "success_url", "fail_url" (where the client will be redirected after the payment will be redirected to after the payment is made) do not have to be passed. These data are automatically taken from merchant settings in your personal cabinet.

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

Important! The query strings must contain only Latin letters and numbers.

GET

/payment/form

Exapmle:

Content type
application/json
Copy
Expand all
Collapse all
{
    "merchant" : "M1VJDHSI6DYXS",
    "order" : "0001",
    "amount" : "16",
    "currency" : "UAH",
    "item_name" : "Samsung TV",
    "first_name" : "IVAN",
    "last_name" : "IVANOV",
    "user_id" : "492235",
    "payment_url" : "https://test.com",
    "country" : "UA",
    "ip" : "212.10.20.75",
    "custom" : "",
    "email": "test@gmail.com",
    "phone": "+35988222763",
    "address": "Avenue Marius Renard 21",
    "city": "Anderlecht",
    "post_code": "1070",
    "region": "stuttgart",
    "lang" : "en"
}

Customer redirection after making a payment

Attention! Direction of the buyer to ”success_url” or “fail_url” is only informational and CAN NOT confirm the success or rejection of payment!

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

The response contains the fields:

  • order_no

    transaction number in the merchant system (the same as in the "order" request);

  • amount

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

  • currency_code

    transaction currency (in which the invoice was formed);

  • item_name

    goods name (if it was transferred);

  • co_inv_id

    unique transaction number;

  • co_inv_st

    transaction status in the payment system (Success or Canceled).

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

Content type
application/json
Copy
Expand all
Collapse all
{
    "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:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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 request

The request contains certain fields:

  • type

    transaction type (payment);

  • merchant

    unique merchant ID;

  • order

    transaction number in the merchant system;

  • amount

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

  • currency

    transaction currency, may take UAH, USD, EUR, KZT, BRL and AZN;

  • card_num

    bank card number;

  • card_exp_month

    bank card expiration month;

  • card_exp_year

    bank card expiration year;

  • card_cvv

    cvv of the bank card;

  • process_url

    URL for sending the transaction summary status

  • item_name

    goods name (an optional field);

  • first_name

    card holder name (Only latin chars are available);

  • last_name

    card holder surname (Only latin chars are available);

  • user_id

    client identifier in the merchant's system (the field is not required);

  • payment_url

    url address of the site in whose favor the payment is made;

  • country

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

  • email

    customer's e-mail

  • phone

    customer's phone number

  • address

    customer's address

  • city

    customer's city

  • post_code

    customer's post code

  • region

    customer's region

  • sign

    digital signature with the merchant’s key. Avialable fields are: “type”, “merchant”, “order”, “amount”, “currency”, “card_num”, “card_exp_month”, “card_exp_year”, “card_cvv” are used. It is hashed using the SHA256 method. (for more details read the “Digital signature in requests” section)

  • 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

    window_width

    window_height

Important! The query strings must contain only Latin letters and numbers.

POST

/api/host2host

Example of the PHP request:

Copy
Expand all
Collapse all
$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",
    "process_url" => "https://test.com/api/callback_url",
    "item_name" => "Samsung TV",
    "first_name" => "IVAN",
    "last_name" => "IVANOV",
    "user_id" => "492235",
    "payment_url" => "https://test.com",
    "country" => "UA",
    "email": "test@gmail.com",
    "phone": "+35988222763",
    "address": "Avenue Marius Renard 21",
    "city": "Anderlecht",
    "post_code": "1070",
    "region": "stuttgart",
    "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 merchant ID;

  • order

    transaction number in the merchant system (the same as in the request);

  • uuid

    unique transaction ID, use it to search or to contact tech support (if necessary);

  • co_inv_id

    unique transaction number;

  • d3_acs_url

    link to the 3DS page, where the customer will be redirected;

  • d3_pareq

    data for passing;

  • d3_md

    data for passing.

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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 certain fields:

  • status

    transaction status (error);

  • code

    error code;

  • description

    description error.

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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 must redirect the customer to the 3DS form. Use the options from the response at the initial request for this,.

Copy
Expand all
Collapse all
<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>

Final request

*Pay attention! Do not mistake d3_pares and d3_pareq:

  • you receive d3_pareq in response to the initial request and send it to the 3DS form;
  • you receive d3_pares from the 3DS form and send in the final request.

The request contains the fields:

  • type

    type (3ds);

  • merchant

    unique merchant ID;

  • uuid

    unique transaction ID (you receive this option in the response at the initial request);

  • order

    transaction number in the merchant system (the same as in the initial request);

  • d3_pares

    you receive it in the response from the 3DS form;

  • d3_md

    data for passing (you receive it in the response at the initial request);

  • sign

    digital signature with the merchant’s key. Avialable fields are: “type”, “merchant”, “order”, “uuid”, “d3_md”. It is hashed using the SHA256 method. (for more details read the “Digital signature in requests” section)

POST

/api/host2host

Example:

Copy
Expand all
Collapse all
$data = [
    "type" => "3ds",
    "merchant" => $merchant ,
    "uuid" => "BILLLINE ID",
    "order" => "Your ID value",
    "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 merchant ID;

  • uuid

    unique transaction ID, use it to search or to contact tech support (if necessary);

  • order

    transaction number in the merchant system (the same as in the request);

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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

    transaction status (error);

  • code

    error code;

  • description

    description error.

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "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”).

For more information read the Callbacks section.

Deposit PIX (host-2-host)

Initial request

The request contains certain fields:

  • type

    transaction type (PIX);

  • merchant

    unique merchant ID;

  • order

    transaction number in the merchant system;

  • amount

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

  • currency

    transaction currency, may take BRL;

  • item_name

    goods name;

  • country

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

  • custom

    additional information about the client;

  • ip

    customer's IP address;

  • sign

    digital signature with the merchant’s key. Avialable fields are: “type”, “merchant”, “order”, “amount”, “currency” are used. It is hashed using the SHA256 method. (for more details read the “Digital signature in requests” section)

POST

/api/h2hpix

Example:

Content type
application/json
Copy
Expand all
Collapse all
{
    "type": "pix",
    "merchant": "M1VJDHSI6DYXS",
    "order": "125327341124",
    "amount": "123.45",
    "currency": "BRL",
    "item_name": "test",
    "country": "BR",
    "custom": "test",
    "ip": "127.0.0.1",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

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

  • status

    transaction status (pending);

  • merchant

    unique merchant ID;

  • order

    transaction number in the merchant system (the same as in the request);

  • uuid

    unique transaction ID, use it to search or to contact tech support (if necessary);

  • co_inv_id

    unique transaction number;

  • qr_code

    string containing the payment address;

  • img

    base64 encoded string view of qr code image;

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "pending",
    "merchant": "QZLF99CVT3WMF",
    "order": "125327341124",
    "uuid": "P1FMNCQDPGI0O",
    "co_inv_id": 15356471,
    "qr_code": "0002012682...A0D28263049620",
    "img": "iVBORw0KGg...UVORK5CYII="
}

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

  • status

    transaction status (error);

  • code

    error code;

  • description

    error description;

Example of the response:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "error",
    "code": "10",
    "description": "The order is already in the system. Request a status."
}

Payment status request (Deposit)

The data transfer method can be POST or GET.

The request contains certain fields:

  • merchant

    unique merchant ID;

  • order

    transaction number in the merchant system;

  • co_inv_id

    unique transaction number (the number is transferred after payment processing to the merchant’s Process URL);

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “order”, “co_inv_id”. It is hashed using the MD5 method. (for more details read the “Digital signature in requests” section)

GET

/payment/status

Examples of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
    "merchant" : "M1VJDHSI6DYXS",
    "order" : "0001",
    "co_inv_id" : "1111111",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

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

  • status

    transaction status:

    Success – the payment is completed successfully (final status)

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

    Fail – the payment is canceled (final status)

    Refund – the payment was refunded (final status)

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

  • order

    transaction number in the merchant system;

  • description

    status description;

  • card_number

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

  • sign

    digital signature with the merchant’s key.

Example of the response – Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "success",
    "order" : "0001",
    "description" : "Merchant payment success",
    "card_number" : "530011******3333",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "Error",
    "order" : "0001",
    "description" : "Merchant payment not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Payouts to the bank card

For correct payouts setup, go to “Personal Account” – “Edit merchant”.

You can find the detailed description of these settings in the “Sign up” section (paragraphs 8-11).

Payout request

The request contains certain fields:

  • merchant

    unique merchant ID;

  • method

    payout method, integer number:

    1 - Visa/Mastercard UAH

    8 - Mastercard USD - this method requires a mandatory field to be passed: "exp_date": "mm/yy", "full_name": "CARD HOLDER"

    9 - Mastercard EUR

    11 - Visa/Mastercard AZN

    12 - Visa/Mastercard KZT

    16 - Visa/Mastercard UAH (Alternative)

    17 - Visa/Mastercard AZN - this method requires a mandatory field to be passed: "exp_date": "mm/yy"

    22 - Visa EUR (Alternative) - this method requires a mandatory field to be passed: "full_name": "CARD HOLDER"

    23 - MasterCard EUR (Alternative) - this method requires a mandatory field to be passed: "full_name": "CARD HOLDER"

    24 - Mobile KZT - this method requires a phone to be passed in field "account" (without "+" sign)

  • payout_id

    outgoing payment number in the merchant’s system;

  • account

    bank card number (Visa or Mastercard);

  • amount

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

  • currency

    transaction currency, must match with the field “method”:

    «UAH» for method 1

    «USD» for method 8

    «EUR» for method 9

    «AZN» for method 11

    «KZT» for method 12

    «UAH» for method 16 (Alternative)

    «AZN» for method 17

    «EUR» for method 22 (Alternative)

    «EUR» for method 23 (Alternative)

    «KZT» for method 24 (Mobile payments)

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “method”, “payout_id”, “account”, “amount”, “currency” are used. It is hashed using the MD5 method (for more details read the “Digital signature in requests” section).

POST

/merchant/api/payout_send

Examples of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
    "merchant" : "M1VJDHSI6DYXS",
    "method" : 1,
    "payout_id" : "000002",
    "account" : "5300111122223333",
    "amount" : "102.81",
    "currency" : "UAH",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

The response contains certain fields:

  • status

    transaction status:

    Success – the payment is completed successfully (final status)

    Pending – the payment is new or is in the line for processing. The Pending status requires an additional request (for more details read the section “Payment Status Request (Payout)”).

    Blocked – The payment is canceled (final status)

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

  • code

    transaction status code;

  • payout_id

    outgoing payment number in the merchant’s system;

  • description

    status description;

  • sign

    digital signature with the merchant’s key.

Example of the response – Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "Success",
    "code" : "0",
    "payout_id" : 000002,
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Pending status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Pending",
    "code": "40",
    "payout_id": 000002,
    "description": "Payment in order",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Error",
    "code": "99",
    "payout_id": "",
    "description": "Sign error",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Final Status (Callback)

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

For more information read the Callbacks section.

Request for payment to bank accounts (SEPA)

The request contains certain fields:

  • merchant

    unique merchant ID;

  • method

    payout method, integer number:

    15 — Payout Iban EUR;

  • payout_id

    the number of the outgoing payment in the merchant’s system;

  • account

    bank account number;

  • full_name

    first name, last name of the client. Maximum length 30 characters;

  • amount

    amount of the transaction in currency, separator character is a period “.”;

  • currency

    transaction currency “EUR”:

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “method”, “payout_id”, “account”, “amount”, “currency”. Hashed using the MD5 method (for more details read the “Digital signature in requests” section).

POST

/merchant/api/payout_send

Example of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
     "merchant" : "M1VJDHSI6DYXS",
     "method" : 15,
     "payout_id" : "000002",
     "account" : "iban adress",
     "full_name" : IVANOV IVAN
     "amount" : "102.81",
     "currency" : "EUR",
     "sign" : "XXXXXXXXXXXXXXXXXX"
 }

The response contains the fields:

  • status

    transaction status:

    Success – the payment was made successfully (the status is final)

    Pending – the payment is new or is in the line for processing. The Pending status requires an additional request (for more details read the “Payment Status Request (payment)” section).

    Blocked – payment rejected (final status)

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

  • code

    transaction status code;

  • payout_id

    the number of the outgoing payment in the merchant’s system;

  • description

    status description;

  • sign

    digital signature with the merchant’s key.

An example of a response is a Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status" : "Success",
     "code" : "0",
     "payout_id" : 000002,
     "description" : "Payment successful. Status final",
     "sign" : "XXXXXXXXXXXXXXXXXX"
 }

An example of a response is the Pending status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status": "Pending",
     "code": "40",
     "payout_id": 000002,
     "description": "Payment in order",
     "sign": "XXXXXXXXXXXXXXXXXX"
 }

An example of a response is the Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status": "Error",
     "code": "99",
     "payout_id": "",
     "description": "Sign error",
     "sign": "XXXXXXXXXXXXXXXXXX"
 }

Final status (callback)

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

For more information read the Callbacks section.

Request for payment to bank accounts (PIX)

The request contains certain fields:

  • merchant

    unique merchant ID;

  • method

    payout method, integer number:

    21 — Payout PIX BRL;

  • payout_id

    the number of the outgoing payment in the merchant’s system;

  • account

    taxpayer Identification Number;

  • pix_key

    PIX user key;

  • amount

    amount of the transaction in currency, separator character is a period “.”;

  • currency

    transaction currency “BRL”:

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “method”, “payout_id”, “account”, “amount”, “currency”. Hashed using the MD5 method (for more details read the “Digital signature in requests” section).

POST

/merchant/api/payout_send

Example of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
     "merchant" : "M1VJDHSI6DYXS",
     "method" : 21,
     "payout_id" : "000002",
     "account" : "1111111122222",
     "pix_key" : "test@test.com",
     "amount" : "102.81",
     "currency" : "BRL",
     "sign" : "XXXXXXXXXXXXXXXXXX"
 }

The response contains the fields:

  • status

    transaction status:

    Success – the payment was made successfully (the status is final)

    Pending – the payment is new or is in the line for processing. The Pending status requires an additional request (for more details read the “Payment Status Request (payment)” section).

    Blocked – payment rejected (final status)

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

  • code

    transaction status code;

  • payout_id

    the number of the outgoing payment in the merchant’s system;

  • description

    status description;

  • sign

    digital signature with the merchant’s key.

An example of a response is a Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status" : "Success",
     "code" : "0",
     "payout_id" : 000002,
     "description" : "Payment successful. Status final",
     "sign" : "XXXXXXXXXXXXXXXXXX"
 }

An example of a response is the Pending status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status": "Pending",
     "code": "40",
     "payout_id": 000002,
     "description": "Payment in order",
     "sign": "XXXXXXXXXXXXXXXXXX"
 }

An example of a response is the Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
     "status": "Error",
     "code": "99",
     "payout_id": "",
     "description": "Sign error",
     "sign": "XXXXXXXXXXXXXXXXXX"
 }

Final status (callback)

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

For more information read the Callbacks section.

Query for Payment Status (Payout)

The query contains certain fields:

  • merchant

    unique merchant ID;

  • payout_id

    outgoing payment number in the merchant’s system;

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant” and “payout_id”. It is hashed using the MD5 method (for more details read the “Digital signature in requests” section).

POST

/merchant/api/payout_status

Examples of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
    "merchant" : "M1VJDHSI6DYXS",
    "payout_id" : "000002",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

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

  • status

    transaction status:

    Success – the payment is completed successfully (final status)

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

    Blocked – the payment is canceled (final status)

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

  • payout_id

    outgoing payment number in the merchant’s system;

  • code

    payment status code;

  • description

    status description;

  • sign

    digital signature with the merchant’s key.

Example of the response – Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "Success",
    "payout_id" : 000002,
    "code" : "0",
    "description" : "Payment successful. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "Error",
    "code" : "8",
    "payout_id" : "",
    "description" : "Transaction not found",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Blocked status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" : "Blocked",
    "payout_id" : 000002,
    "code" : "80",
    "description" : "Payment error. Status final",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

Balance request

The request contains certain fields:

  • merchant

    unique merchant ID;

  • currency

    requested currency (UAH, USD, EUR, KZT, BRL and AZN);

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “currency”. It is hashed using MD5 method (for more details read the “Digital signature in requests” section).

POST

/payment/balance

Examples of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
    "merchant" : "M1VJDHSI6DYXS",
    "currency" : "UAH",
    "sign" : "XXXXXXXXXXXXXXXXXX"
}

The response contains certain fields:

  • status

    request status:

    Success – request successful

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

  • currency

    requested currency (UAH, USD, EUR, KZT, BRL and AZN);

  • balance

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

  • description

    description (”Wallet balance”);

  • sign

    digital signature with the merchant’s key.

Example of the response – Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Success",
    "currency": "UAH",
    "balance": 212.07,
    "description": "Wallet balance",
    "sign": "XXXXXXXXXXXXXXXXXX"
}

Example of the response – Error status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Error",
    "merchant": "M1VJDHSI6DYXS",
    "description": "Merchant not found or not Approved"
}

Payments list request

The data transfer method can be POST or GET.

Payments lists requests are processed not more than one per minute.

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

The requests contains certain fields:

  • merchant

    unique merchant ID;

  • currency

    requested currency (UAH, USD, EUR, KZT, BRL and AZN);

  • 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 "YYYY-MM-DD HH:ii:ss" format;

  • finish_date

    date and time of the end of the period in the "YYYY-MM-DD HH:ii:ss" format;

  • status

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

  • type

    transaction type (withdrawal or deposit);

  • sign

    digital signature with the merchant’s key. Avialable fields are: “merchant”, “currency”, “order”, “start_date”, “finish_date”, “status”, “type”. It is hashed using MD5 method (for more details read the “Digital signature in requests” section).

GET

/api/payment-list

Examples of the request:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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 transaction number;

  • uid

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

  • order_id

    transaction number in the merchant system;

  • subtotal

    amount transfered:

    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” added to “subtotal”

  • fee_fixed

    fee rate (if the fee type is fixed):

    In case of “Deposit” deducted from “total”

    In case of “Withdrawal” added to “subtotal”

  • total

    total transaction amount:

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

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

  • type

    transaction type (withdrawal or deposit);

  • status

    transaction status (Success, Pending, Blocked, Refund);

  • created_at

    transaction creation date and time;

  • updated_ad

    transaction processing date and time.

Example of the response – Success status:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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:

Content type
application/json
Copy
Expand all
Collapse all
{
    "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:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Error",
    "description": "Please send one request per minute"
}

Currency rates request

The data transfer method can be POST or GET

Request fields

  • merchant

    merchant ID

  • currency_from

    base currency

GET

/api/rates

Content type
application/json
Copy
Expand all
Collapse all
{
    "status":"success",
    "description":"Description of the response",
    "rates": {
          "CURR1":VAL1,
          "CURR2":VAL2,
    …}
}

Example:

Content type
application/json
Copy
Expand all
Collapse all
{
    "status":"success",
    "description":"Rates from UAH",
    "rates":{
          "USD":0.0247,
          "EUR":0.0228
    }
}

or in case of error

Content type
application/json
Copy
Expand all
Collapse all
{
    "status" => "Error",
    "description" => "Error description"
}

Request for currency exchange

Fields for recurring payment

  • merchant

    merchant ID

  • order

    payment number in the merchant’s system

  • amount

    exchange amount

  • currency_from

    exchange currency currency_to – result

  • currency_to

    result currency

  • currency sign

    request signature using sha256 encryption method

POST

/api/exchange

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "success",
    "description": "Currency exchange success",
    "transInfo":{
        "order":"order",
        "uuid":"uuid",
        "amount": amount,
        "fee":0,
        "currency_from":"currency_from",
        "converted_amount": converted_amount,
        "currency_to":"currency_to",
        "rate":rate
    }
}

or in case of error

Content type
application/json
Copy
Expand all
Collapse all
{
    "status": "Error",
    "description" => "Error description"
}

Status codes

Status code Status Final Description
0 Success Yes Payout successful
2 Error No Input data error
3 Error No Payment method blocked
4 Error No Marchant blocked
5 Error No Payout currency error
6 Error No Merchant account blocked
7 Error No The amount exceeds the balance
8 Error No Transaction ID not found (Contact technical support for details)
10 Error No Repeated withdrawal request, transaction status request required
40 Pending No Transaction in processing
80 Blocked Yes Refused to pay
99 Error No Signature error in request
100 Error No The error is not documented