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

1. Создание платежа
2. Проверка платежа
3. Список платежей
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, ZEC – Z-Cash, BCH – Bitcoin Cash. CURRENCY – валюта эквивалент, которой в размере VALUE, запрашивается в криптовалюте KIND. Для пары KIND-CURRENCY должна существовать одноименная торговая пара.
Согласно второму варианту в запросе напрямую указывается сумма в криптовалюте:
http(s)://API_HOST/v1/payment/<KIND>/create/<VALUE>
Для криптовалюты Z-Cash имеется дополнительный необязательный параметр ADDRESS. ADDRESS может принимать два значения: z и t. В случае указания первого значения платеж будет на z-адрес (Shielded, невиден в блокчейне) версии Sapling. Если ADDRESS отсутствует или равен второму варианту в данных для платежа будет указан t-адрес (Transparent, транзакции с таким типом адреса прозрачны в блокчейне).
URL запроса с параметром ADDRESS для варианта с CURRENCY:
http(s)://API_HOST/v1/payment/zec/create/<CURRENCY>/<VALUE>/address/<ADDRESS>
URL запроса с параметром ADDRESS для варианта без указания CURRENCY:
http(s)://API_HOST/v1/payment/zec/create/<VALUE>/address/<ADDRESS>
SIGNATURE, для варианта с CURRENCY, вычисляется по формуле:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+CURRENCY+';'+VALUE+';'+PRIVATE_KEY)
SIGNATURE, для варианта с CURRENCY и параметром ADDRESS, вычисляется по формуле:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+CURRENCY+';'+VALUE+';'+ADDRESS+';'+PRIVATE_KEY)
SIGNATURE, для варианта без CURRENCY, вычисляется по формуле:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+VALUE+';'+PRIVATE_KEY)
SIGNATURE, для варианта без CURRENCY, но с параметром ADDRESS вычисляется по формуле:
SHA512(PUBLIC_KEY+';'+RND+';'+KIND+';'+VALUE+';'+ADDRESS+';'+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 – полученное количество подтверждений сети;
CONFIRMS_NEEDED – требуемое количество подтверждений в сети криптовалюты KIND, при получении которых платеж будет зачислен;
BALANCE – сумма полученная на адрес CC_ADDRESS через блокчейн криптовалюты (вид платежа внешний);
UNLOCKED_BALANCE – сумма полученная на адрес CC_ADDRESS по транзакции(ям), которая(ые) имеет(ют) количество подтверждений CONFIRMS_NEEDED;
INCOME – принятая к зачислению сумма на момент API-запроса;
TYPE – тип платежа;
STATUS – статус/состояние платежа;
QR_URL – относительный URL (без домена) с изображением QR-кода с реквизитами для оплаты;
CREATED_AT – время создания платежа;
PAY_TIMEOUT – время (в секундах), в течение которого система будет проверять наличие транзакции на адрес CC_ADDRESS;
CONFIRM_TIMEOUT – время (в секундах), в течение которого система будет проверять количество подтверждений сети если транзакция (с суммой не менее указанной в CC_VALUE) успеет появиться за время PAY_TIMEOUT.
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"}]