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).
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:
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:
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
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.
-
co_error_resolution
payment error description
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:
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_error_resolution
payment error description
-
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:
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:
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, INR 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.
Exapmle:
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:
Example of the response in case of payment cancellation:
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.
Example of the PHP request:
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:
If the payment is canceled, the response contains certain fields:
-
status
transaction status (error);
-
code
error code;
-
description
description error.
Example of the response:
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,.
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)
Example:
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:
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:
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)
Example:
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:
If the payment is canceled, the response contains certain fields:
-
status
transaction status (error);
-
code
error code;
-
description
error description;
Example of the response:
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)
Examples of the request:
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);
-
error_resolution
payment error description;
-
sign
digital signature with the merchant’s key.
Example of the response – Success status:
Example of the response – Error status:
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).
Examples of the request:
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:
Example of the response – Pending status:
Example of the response – Error status:
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).
Example of the request:
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:
An example of a response is the Pending status:
An example of a response is the Error status:
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).
Example of the request:
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:
An example of a response is the Pending status:
An example of a response is the Error status:
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 (UPI)
The request contains certain fields:
-
merchant
unique merchant ID;
-
method
payout method, integer number:
26 — Payout UPI INR;
-
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;
-
customs_phone
customer's phone number, +91XXXXXXXXXX;
-
customs_email
customer's e-mail;
-
customs_ifsc
IFSC (Indian Financial System Code);
-
customs_ip
client IP address;
-
amount
amount of the transaction in currency, separator character is a period “.”;
-
currency
transaction currency “INR”;
-
sign
digital signature with the merchant’s key. Avialable fields are: “merchant”, “method”, “payout_id”, “account”, “amount”, “currency”, “customs_phone”, “customs_email”, “customs_ifsc”, “customs_ip”. Hashed using the MD5 method (for more details read the “Digital signature in requests” section).
Example of the request:
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:
An example of a response is the Pending status:
An example of a response is the Error status:
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 payout to bank accounts (IBAN)
The request contains the following fields:
-
merchant
unique merchant identifier;
-
method
payout method, integer number:
34 — Payout Iban UAH;
-
payout_id
merchant system outgoing payment number;
-
account
IBAN bank account number;
-
full_name
first and last name in Latin characters. Maximum length is 30 characters;
-
customs_card
client’s payment card number;
-
customs_inn
clients identification code;
-
amount
amount of the transaction in currency, separator character is a period “.”;
-
currency
transaction currency “UAH”;
-
sign
digital signature with the merchant’s key. All fields are used. Hashed using the MD5 method (for more details read the “Digital signature in requests” section).
Example of the request:
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:
An example of a response is the Pending status:
An example of a response is the Error status:
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).
Examples of the request:
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:
Example of the response – Error status:
Example of the response – Blocked status:
Balance request
The request contains certain fields:
-
merchant
unique merchant ID;
-
currency
requested currency (UAH, USD, EUR, KZT, BRL, INR 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).
Examples of the request:
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, INR 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:
Example of the response – Error status:
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, INR 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).
Examples of the request:
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:
Example of the response – Blocked status:
Example of the response – Error status:
Currency rates request
The data transfer method can be POST or GET
Request fields
-
merchant
merchant ID
-
currency_from
base currency
Example:
or in case of error
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
or in case of error
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 |