Функции управления платежом

API-запрос осуществляется методом POST протокола HTTP к одному из указанных в Кабинете хостов. Общий вид URL API-запроса:

http(s)://API_HOST/v1/<function>/<params>

Тело (DATA) POST-запроса всегда состоит из трех параметров:

public_key=<PUBLIC_KEY>&rnd=<RND>&signature=<SIGNATURE>

PUBLIC_KEY – открытый ключ пользователя, RND – случайный набор латинских букв и цифр, SIGNATURE – подпись запроса, PRIVATE_KEY – закрытый ключ пользователя.

Открытый и закрытый ключи пользователя уникальны для каждого пользователя и отображены в Кабинете. RND генерирует отправитель запроса, в целях безопасности рекомендуется генерировать новый RND на каждый запрос.

Во всех приведенных ниже примерах открытый ключ (PUBLIC_KEY):

67DbHjAodk9Cbic98mG98492d4N1IB29m51P3j

закрытый ключ (PRIVATE_KEY):

35CJ1KMG57HPjNaF4MCEe9HiAEKF39eNigikJ2393

RND:

J04PDiMH9pH2k10Il713D5c76f1

За каждый API-запрос начисляется определенное количество баллов (вес функции), сумма таких баллов полученных за 1 минуту не должна превышать лимит установленный для пользователя, который по умолчанию равен 10. Свяжитесь с тех. поддержкой для увеличения лимита.

1. Функция payment-create, создание платежа

Вес функции payment-create равен 3 баллам.

Общий вид

Запрос может быть выполнен в двух вариантах. Согласно первому варианту в запросе указывается требуемая к получению сумма в эквиваленте другой валюты по текущему биржевому курсу:

http(s)://API_HOST/v1/payment/<KIND>/create/<CURRENCY>/<VALUE>

KIND – название криптовалюты в сокращенном виде, допустимые значения: BTC – Bitcoin, LTC – Litecoin, DASH – Dash, XMR – Monero, BCH – Bitcoin Cash. CURRENCY – валюта эквивалент, которой в размере VALUE, запрашивается в криптовалюте KIND. Для пары KIND-CURRENCY должна существовать одноименная торговая пара.

Согласно второму варианту в запросе напрямую указывается сумма в криптовалюте:

http(s)://API_HOST/v1/payment/<KIND>/create/<VALUE>

SIGNATURE, для варианта с CURRENCY, вычисляется по формуле:

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

SIGNATURE, для варианта без CURRENCY, вычисляется по формуле:

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

Ответ (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 – внутренний идентификатор платежа;

DECLARED_VALUE – запрашиваемая сумма в валюте DECLARED_CURRENCY;

KIND – название криптовалюты в сокращенном виде;

CC_VALUE – запрашиваемая сумма в криптовалюте KIND;

CC_ADDRESS – адрес криптовалюты KIND, на который ожидается перевод;

CONFIRMS_NEEDED – требуемое количество подтверждений в сети криптовалюты KIND, при получении которых платеж будет зачислен;

QR_URL – относительный URL (без домена) с изображением QR-кода с реквизитами для оплаты;

CREATED_AT – время создания платежа;

PAY_TIMEOUT – время (в секундах), в течение которого система будет проверять наличие транзакции на адрес CC_ADDRESS;

CONFIRM_TIMEOUT – время (в секундах), в течение которого система будет проверять количество подтверждений сети если транзакция (с суммой не менее указанной в CC_VALUE) успеет появиться за время PAY_TIMEOUT.

Пример №1

URL ЗАПРОСА:

http(s)://API_HOST/v1/payment/btc/create/usdt/10

DATA ЗАПРОСА:

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

JSON-ОТВЕТ:

{"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}

Пример №2

URL ЗАПРОСА:

http(s)://API_HOST/v1/payment/ltc/create/0.5

DATA ЗАПРОСА:

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

JSON-ОТВЕТ:

{"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. Функция payment-check, проверка платежа

Вес функции payment-check равен 1 баллу.

Общий вид

http(s)://API_HOST/v1/payment/<PAYMENT_ID>/check

PAYMENT_ID – внутренний идентификатор платежа, возвращается функцией payment-create.

SIGNATURE вычисляется по формуле:

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

Ответ сервера зависит от типа транзакции (если таковая имеется), которая была совершена на адрес платежа. Платеж может быть совершен через внутренний перевод (транзакция с одного счета системы на адрес другого счета в системе) и внешний (транзакция через блокчейн криптовалюты). Считается, что перевод имеет тип внутренний (type = internal) если первая транзакция по адресу платежа внутренняя, если первая транзакция внешняя – тип внешний (type = external), если транзакций на адрес платежа не обнаружено – тип неопределен (type = undef).

Смешанный платеж не поддерживается, тип определяется первой полученной транзакцией и, если получена не вся требуемая сумма, платеж в дальнейшем будет мониторить только транзакции этого же типа.

Ответ (JSON) для неопределенного и внешнего прихода

{
	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
}

Ответ (JSON) для внутреннего прихода

{
	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 – внутренний идентификатор платежа;

DECLARED_VALUE – запрашиваемая сумма в валюте DECLARED_CURRENCY;

KIND – название криптовалюты в сокращенном виде;

CC_VALUE – запрашиваемая сумма в криптовалюте KIND;

CC_ADDRESS – адрес криптовалюты KIND, на который ожидается перевод;

CONFIRMS_RECEIVED – полученное количество подтверждений сети;

BALANCE – сумма полученная на адрес CC_ADDRESS через блокчейн криптовалюты (вид платежа внешний);

UNLOCKED_BALANCE – сумма полученная на адрес CC_ADDRESS по транзакции(ям), которая(ые) имеет(ют) количество подтверждений CONFIRMS_NEEDED;

INCOME – принятая к зачислению сумма на момент API-запроса;

TYPE – тип платежа;

STATUS – статус/состояние платежа;

QR_URL – относительный URL (без домена) с изображением QR-кода с реквизитами для оплаты;

CREATED_AT – время создания платежа;

PAY_TIMEOUT – время (в секундах), в течение которого система будет проверять наличие транзакции на адрес CC_ADDRESS;

TYPE может иметь следующие значения:

undef – тип платежа неопределен (по адресу платежа не получено ни одной транзакции какого-либо типа);

external – внешний платеж (на адрес платежа получена внешняя транзакция);

internal – внутренний платеж (на адрес платежа получена внутренняя транзакция).

Для внутреннего платежа отсутствуют поля CONFIRMS_RECEIVED, CONFIRMS_NEEDED, BALANCE, UNLOCKED_BALANCE и CONFIRM_TIMEOUT. Данные параметры отображают состояние ончейн-транзакции (внешней) и теряют всякий смысл для внутренней.

STATUS может иметь следующие значения:

CONFIRM_TIMEOUT – ИСТЕКЛО ВРЕМЯ ПОДТВЕРЖДЕНИЯ (платеж отменен, помещен в архив);

CANCELLED_INSUFFICIENT_FUNDS – ОТМЕНЕН, НЕДОСТАТОЧНО СРЕДСТВ (платеж отменен, помещен в архив);

CANCELLED_NO_TRANSACTION – ТРАНЗАКЦИЯ ОТСУТСТВУЕТ (платеж отменен, помещен в архив);

WAITING_FOR_TRANSACTION – В ОЖИДАНИИ ТРАНЗАКЦИИ (платеж ожидает транзакцию в течение PAY_TIMEOUT);

WAITING_FOR_CONFIRMS – В ОЖИДАНИИ ПОДТВЕРЖДЕНИЙ (платеж ожидает CONFIRMS_NEEDED подтверждений в течение CONFIRM_TIMEOUT);

INSUFFICIENT_FUNDS – НЕДОСТАТОЧНО СРЕДСТВ (платеж ожидает транзакцию с недостающей суммой в течение PAY_TIMEOUT с момента CREATED_AT);

COMPLETED – ЗАВЕРШЕНА (платеж успешно завершен).

Пример

URL ЗАПРОСА:

http(s)://API_HOST/v1/payment/4479/check

DATA ЗАПРОСА:

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

JSON-ОТВЕТ:

{"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. Функция payment-list, список платежей

Вес функции payment-list равен 4 баллам.

Общий вид

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

OFFSET – смещение в страницах, 1 страница содержит 40 платежей.

Список платежей отсортирован в обратном порядке, первый в списке – последний на момент запроса платеж.

SIGNATURE вычисляется по формуле:

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

Ответ (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) – внутренний идентификатор платежа, KIND_(1,2,...,N) – название криптовалюты в сокращенном виде, CC_VALUE_(1,2,...,N) – запрашиваемая сумма в криптовалюте KIND_(1,2,...,N), STATUS_(1,2,...,N) – статус/состояние платежа.

STATUS принимает значение такие же как в функции payment-check.

Пример

URL ЗАПРОСА:

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

DATA ЗАПРОСА:

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

JSON-ОТВЕТ:

[{"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"}]