Payment management functions

1. Creating a payment
2. Checking a payment
An API request is HTTP POST request to one of the hosts specified in the User's Dashboard. General view of an API request URL:
http(s)://API_HOST/v1/<function>/<params>
Data of the POST request always has 3 parameters:
public_key=<PUBLIC_KEY>&rnd=<RND>&signature=<SIGNATURE>
PUBLIC_KEY – user's public key, RND – random set of latin letters and numbers, SIGNATURE – signature of API request, PRIVATE_KEY – user's private key.
The public and private keys of user are unique for each user and are displayed in the User's Dashboard. The request sender generates RND, for security reasons it is recommended to generate a new RND for each request.
For all examples below user's public key (PUBLIC_KEY) is equal
67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j
private key (PRIVATE_KEY) is
35CJ1KMG57HPjNaF4MCEe9HiAEKF39eNigikJ2393
RND is
J04PDiMH9pH2k10Il713D5c76f1
Every API function has certain weight, the total weight of functions per 1 minute must be equal or less than limit of weight that is set for the user. Default limit is 10 scores. Contact support to increase the limit.

1. Function "payment-create"

Weight of function "payment-create" is 3 scores.

General

The request can be executed in two ways. According to the first way the request specifies the amount required to receive in the equivalent of another currency at the current exchange rate:
http(s)://API_HOST/v1/payment/<KIND>/create/<CURRENCY>/<VALUE>
KIND – abbreviated cryptocurrency name, allowed values: BTC – Bitcoin, LTC – Litecoin, DASH – Dash, XMR – Monero, ZEC – Z-Cash, BCH – Bitcoin Cash. CURRENCY – the currency equivalent, which in the amount of VALUE, is requested in the KIND cryptocurrency. There must be a trading pair of the same name for a KIND-CURRENCY pair.
According to the second way the request directly indicates the amount in cryptocurrency:
http(s)://API_HOST/v1/payment/<KIND>/create/<VALUE>
There is additional optional parameter ADDRESS for Z-Cash cryptocurrency. ADDRESS can take 2 values: z and t. If the first value is specified, the payment will be to the Sapling version z-address (Shielded, not visible in the blockchain). If ADDRESS is missing or is equal to the second option, payment data will have the t-address (Transparent, visible in the blockchain).
Request URL with CURRENCY and ADDRESS parameters:
http(s)://API_HOST/v1/payment/zec/create/<CURRENCY>/<VALUE>/address/<ADDRESS>
Request URL with ADDRESS but without CURRENCY parameter:
http(s)://API_HOST/v1/payment/zec/create/<VALUE>/address/<ADDRESS>
SIGNATURE for the request with CURRENCY is calculated by the formula:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+CURRENCY+';'+VALUE+';'+PRIVATE_KEY)
SIGNATURE for the request with CURRENCY and ADDRESS parameters is calculated by the formula:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+CURRENCY+';'+VALUE+';'+ADDRESS+';'+PRIVATE_KEY)
SIGNATURE for the request without CURRENCY is calculated by the formula:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+VALUE+';'+PRIVATE_KEY)
SIGNATURE for the request without CURRENCY but with ADDRESS parameter is calculated by the formula:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+VALUE+';'+ADDRESS+';'+PRIVATE_KEY)

Response (JSON)

{
payment_id: PAYMENT_ID,
declared_value: DECLARED_VALUE,
declared_currency: DECLARED_CURRENCY,
kind: KIND,
cc_value: CC_VALUE,
cc_address: CC_ADDRESS,
confirms_needed: CONFIRMS_NEEDED,
qr: QR_URL,
created_at: CREATED_AT,
pay_timeout: PAY_TIMEOUT,
confirm_timeout: CONFIRM_TIMEOUT
}
PAYMENT_ID – internal payment ID;
DECLARED_VALUE – requested amount in the currency DECLARED_CURRENCY;
KIND – abbreviated cryptocurrency name;
CC_VALUE – requested amount in the cryptocurrency KIND;
CC_ADDRESS – address of cryptocurrency KIND, that is waiting for transaction;
CONFIRMS_NEEDED – required confirmation count in the cryptocurrency blockchain to make the payment accepted;
QR_URL – relative URL (without host) of the payment QR code;
CREATED_AT – payment creation time;
PAY_TIMEOUT – period of time (in seconds) during which the system will searching for transaction to the address CC_ADDRESS;
CONFIRM_TIMEOUT – period of time (in seconds) during which the system will checking count of confirmations if a transaction (with amount not less than CC_VALUE) would be found before not PAY_TIMEOUT over.

Example #1

REQUEST URL:
http(s)://API_HOST/v1/payment/btc/create/usdt/10
REQUEST DATA:
public_key=67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j&rnd=J04PDiMH9pH2k10Il713D5c76f1&signature=d7832a3a036094061cfd146cec27bbe438a49d62bcadda9199a804dc6b6befa4c333e04a7dacd9ca555568155cb37e85397e64f720f8cb88f794f5b8180e5a9f
JSON RESPONSE:
{"payment_id":"af9b0cf5e2438916ec797a103bbb7b63","declared_value":"10.0","declared_currency":"usdt","kind":"btc","cc_value":"0.00026326","cc_address":"3NYCnqKFLkp8xfBuxajUBFTBTSMmVYx8ge","confirms_needed":1,"qr":"/qr/44ena3a52lc2c.png","created_at":"2022-02-04T15:51:57.302+03:00","pay_timeout":3600,"confirm_timeout":604800}

Example #2

REQUEST URL:
http(s)://API_HOST/v1/payment/ltc/create/0.5
REQUEST DATA:
public_key=67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j&rnd=J04PDiMH9pH2k10Il713D5c76f1&signature=eed6dfbc9487b0d61d14e49b61ed29d3d3c744989289885d569b916296f8e1269a11403ebe356578fdd165e546b66719c8f3efd16fff583142d7a70648384809
JSON RESPONSE:
{"payment_id":"78a90dd3d0cf400673eb46f4c0f04f5b","declared_value":null,"declared_currency":"ltc","kind":"ltc","cc_value":"0.5","cc_address":"MTXfyRooE4D1q5euMMztgubhxpyBWVDNG4","confirms_needed":3,"qr":"/qr/gh6o7ga8j3n4am.png","created_at":"2022-02-04T17:08:07.574+03:00","pay_timeout":1800,"confirm_timeout":10800}

2. Function "payment-check"

Weight of function "payment-check" is 1 score.

General

http(s)://API_HOST/v1/payment/PAYMENT_ID/check
PAYMENT_ID – internal payment ID, that is returned by payment-create.
SIGNATURE is calculated by the formula:
SHA512(PUBLIC_KEY+';'+RND+';'+PAYMENT_ID+';'+PRIVATE_KEY)
Type of transaction that sent to the payment address (CC_ADDRESS) indicates the type of payment. Payment can get internal (from one cryptocurrency wallet to another inside the system) transaction and external (transaction via blockchain). The type of payment will be internal (type = internal) if the first transaction to payment address is internal, if the first external the payment type will be external (type = external), if the payment address doesn't get a transaction yet the type of payment will be undefined (type = undef).
Mixed payment is not supported, the first received transaction defines the type of payment, if the first transaction doesn't have full amount the payment will be searching for transactions the same type only.

Response (JSON) for undefined and external types of income

{
payment_id: PAYMENT_ID,
declared_value: DECLARED_VALUE,
declared_currency: DECLARED_CURRENCY,
kind: KIND,
cc_value: CC_VALUE,
cc_address: CC_ADDRESS,
confirms_received: CONFIRMS_RECEIVED,
confirms_needed: CONFIRMS_NEEDED,
balance: BALANCE,
unlocked_balance: UNLOCKED_BALANCE,
income: INCOME,
type: TYPE,
status: STATUS,
qr: QR_URL,
created_at: CREATED_AT,
pay_timeout: PAY_TIMEOUT,
confirm_timeout: CONFIRM_TIMEOUT
}

Response (JSON) for internal type of income

{
payment_id: PAYMENT_ID,
declared_value: DECLARED_VALUE,
declared_currency: DECLARED_CURRENCY,
kind: KIND,
cc_value: CC_VALUE,
cc_address: CC_ADDRESS,
income: INCOME,
type: TYPE,
status: STATUS,
qr: QR_URL,
created_at: CREATED_AT,
pay_timeout: PAY_TIMEOUT
}
PAYMENT_ID – internal payment ID;
DECLARED_VALUE – requested amount in the currency DECLARED_CURRENCY;
KIND – abbreviated cryptocurrency name;
CC_VALUE – requested amount in the cryptocurrency KIND;
CC_ADDRESS – address of cryptocurrency KIND, that is waiting for transaction;
CONFIRMS_RECEIVED – received confirmations count;
CONFIRMS_NEEDED – required confirmation count in the cryptocurrency blockchain to make the payment accepted;
BALANCE – amount that received to address CC_ADDRESS via blockchain (external);
UNLOCKED_BALANCE – amount that received to address CC_ADDRESS from transactions with required count of confirmations (CONFIRMS_NEEDED);
INCOME – amount accepted for crediting at the time of the API request;
TYPE – type of payment;
STATUS – status of payment;
QR_URL – relative URL (without host) of the payment QR code;
CREATED_AT – payment creation time;
PAY_TIMEOUT – period of time (in seconds) during which the system will searching for transaction to the address CC_ADDRESS;
CONFIRM_TIMEOUT – period of time (in seconds) during which the system will checking count of confirmations if a transaction (with amount not less than CC_VALUE) would be found before not PAY_TIMEOUT over.
TYPE can have the next values:
undef – type of the payment is undefined (CC_ADDRESS has not got transaction of any type yet);
external – external payment (CC_ADDRESS has got external transaction);
internal – internal payment (CC_ADDRESS has got internal transaction).
The response of internal payment doesn't have CONFIRMS_RECEIVED, CONFIRMS_NEEDED, BALANCE, UNLOCKED_BALANCE and CONFIRM_TIMEOUT fields. These fields show status of on-chain transaction (external) and lose their meaning for internal transactions.
STATUS can have the next values:
CONFIRM_TIMEOUT – the time for getting confirmations has expired (canceled);
CANCELLED_INSUFFICIENT_FUNDS – payment has received insufficient funds and the time for paying has expired (canceled);
CANCELLED_NO_TRANSACTION – no transaction (canceled);
WAITING_FOR_TRANSACTION – payment is waiting for transaction within PAY_TIMEOUT seconds;
WAITING_FOR_CONFIRMS – payment has got full amount, but it waiting for CONFIRMS_NEEDED confirmations within CONFIRM_TIMEOUT seconds;
INSUFFICIENT_FUNDS – payment is waiting for transaction with the missing amount within PAY_TIMEOUT seconds since CREATED_AT;
COMPLETED – payment completed successfully.

Example

REQUEST URL:
http(s)://API_HOST/v1/payment/78a90dd3d0cf400673eb46f4c0f04f5b/check
REQUEST DATA:
public_key=67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j&rnd=J04PDiMH9pH2k10Il713D5c76f1&signature=548596bda393c894a0b5fe94bb47473d7f605ca20eadb6276ccc51e8240fb018d12a03e809fbbcd9a2e8913726fe69e6b74a0023d93d507acee1dd4f5fd58421
JSON RESPONSE:
{"payment_id":"78a90dd3d0cf400673eb46f4c0f04f5b","declared_value":null,"declared_currency":"ltc","kind":"ltc","cc_value":"0.5","cc_address":"MTXfyRooE4D1q5euMMztgubhxpyBWVDNG4","confirms_received":0,"confirms_needed":3,"balance":0.0,"unlocked_balance":0.0,"income":0.0,"type":"undef","status":"WAITING_FOR_TRANSACTION","qr":"/qr/gh6o7ga8j3n4am.png","created_at":"2022-02-04T17:08:07.000+03:00","pay_timeout":1800,"confirm_timeout":10800}