Payment management functions

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, 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>

SIGNATURE for the request with CURRENCY is calculated by the formula:

SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+CURRENCY+';'+VALUE+';'+PRIVATE_KEY)

SIGNATURE for the request without CURRENCY is calculated by the formula:

SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+VALUE+';'+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 – number of required confirmations 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 number 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":3290,"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":3291,"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 – number of received confirmations;

CONFIRMS_NEEDED – number of required confirmations 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 confirmed transactions (transactions which have required number 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 the number 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/4479/check

REQUEST DATA:

public_key=67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j&rnd=J04PDiMH9pH2k10Il713D5c76f1&signature=f9e1a0b4ebeb3913181f8e2d965bad1f4f45493eaa6d3565c58a7c04cb97910a6073f4cdaa949fb73ee5b586a8f7ac1f58f1a91152b2540f7f0d7b16a471c920

JSON RESPONSE:

{"payment_id":4479,"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}

3. Function "payment-list"

Weight of function "payment-list" is 4 score.

General

http(s)://API_HOST/v1/payment/list/<OFFSET>

OFFSET – offset is in pages, 1 page has 40 payments.

List of payments is reverse ordered, the first in the list is the latest at the moment.

SIGNATURE is calculated by the formula:

SHA512(PUBLIC_KEY+';'+RND+';'+OFFSET+';'+PRIVATE_KEY)

Response (JSON)


[
	{
		payment_id: PAYMENT_ID_1,
		kind: KIND_1,
		cc_value: CC_VALUE_1,
		status: STATUS_1
	},
	{
		payment_id: PAYMENT_ID_2,
		kind: KIND_2,
		cc_value: CC_VALUE_2,
		status: STATUS_2
	},	
	...
	{
		payment_id: PAYMENT_ID_N,
		kind: KIND_N,
		cc_value: CC_VALUE_N,
		status: STATUS_N
	}
]

PAYMENT_ID_(1,2,...,N) – internal payment ID, KIND_(1,2,...,N) – abbreviated cryptocurrency name, CC_VALUE_(1,2,...,N) – requested amount in the cryptocurrency KIND_(1,2,...,N), STATUS_(1,2,...,N) – status of payment.

STATUS can have the same values as in the function payment-check.

Example

REQUEST URL:

http(s)://API_HOST/v1/payment/list/1

REQUEST DATA:

public_key=67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j&rnd=J04PDiMH9pH2k10Il713D5c76f1&signature=6aa8f3d80df4b946856f72374053d4e93fe6e2eb155f0f6d30e57a6c1cb3f1a8f432be18c303f49e68854436bbd04c6cc90148e93831955204416a6a0388018c

JSON RESPONSE:

[{"payment_id":3462,"kind":"xmr","cc_value":"0.100247276616","status":"COMPLETED"},{"payment_id":3461,"kind":"btc","cc_value":"0.00072948","status":"CANCELLED_NO_TRANSACTION"}, {"payment_id":3450,"kind":"xmr","cc_value":"0.292189039513","status":"COMPLETED"},{"payment_id":3447,"kind":"ltc","cc_value":"0.30952706","status":"COMPLETED"}]