Документация API merchant.cryptex.net
Введение
Cryptex Merchant — платежный шлюз приема платежей в криптовалюте для онлайн-магазинов и не только. При помощи сервиса продажа товаров и предоставление услуг за цифровые активы станут такими же простыми, как и обычные платежи через фиатные платежные шлюзы.
Для интеграции CryptexPay в свою систему бизнесу не придется проводить сложные настройки на своей стороне — достаточно подключить платежный шлюз по API к CRM и сайту, а вся информация будет доступна в личном кабинете мерчанта на https://merchant.cryptex.net. Таким образом, любой онлайн-магазин или поставщик услуг сможет значительно расширить географию охвата, а, в отличие от фиатных платежных шлюзов, конвертация криптовалюты происходит с меньшей комиссией, чем автоматический обмен национальных валют.
Этапы подготовки
Необходимо зарегистрировать аккаунт по ссылке https://merchant.cryptex.net/ru/auth/signup для получения доступа к личному кабинету Merchant. К одному аккаунту может быть привязан только 1 магазин/сервис.
После регистрации происходит автоматическое перенаправление на страницу настроек и генерируется уникальный Ключ вашего сервиса.
Необходимо заполнить следующие поля на странице настроек для работы через Merchant:
- Валюта, которую вы хотите принимать через мерчант.
- Контактная информация, которая будет отображаться на страницах во время оплаты. Доступны 3 типа контактов: email, jabber, telegram. Cуммарно не больше 5 контактов.
- Название магазина — это название вашего сервиса, которое будет отображаться на страницах платежей в Merchant.
- URL-адрес магазина — адрес вашего сервиса.
- URL-адрес успешного платежа — это адрес, на который Merchant будет перенаправлять Покупателя при успешном выполнении платежа.
- Webhook URL-адрес успешного платежа — адрес для отправки уведомлений об успешном выполнении платежа.
Интерфейс Cryptex Merchant
Для приема онлайн-платежей веб-сайт Продавца должен перенаправить Покупателя на Cryptex Merchant для оплаты товаров или услуг, заказанных на веб-сайте Продавца. После успешного завершения платежа Покупатель будет перенаправлен обратно на веб-сайт Продавца.
Процесс приема платежей через Merchant состоит из следующих шагов:
Страница заказа на сайте продавца. Покупатель выбирает товары или услуги в интернет-магазине и решает купить. Продавец отображает общую сумму покупки и Покупатель переходит к оплате своего заказа, нажав на соответствующую ссылку. Сайт продавца отправляет POST-запрос на создание платежа и перенаправляет Покупателя на Cryptex Merchant. В запросе обязательно должен быть передан ключ магазина (key, указан в личном кабинете Merchant), сумма заказа, валюта (currency, USD), идентификационный номер заказа (order id). В ответ на запрос формируется идентификационный номер платежа (payment_id).
Страница выбора валюты платежа на сайте Merchant — доступна по адресу https://merchant.cryptex.net/pay/{payment_id}. Покупателю отображаются доступные для оплаты валюты, дата заказа, номер заказа, название сайта Продавца. Покупатель также может вернуться обратно на сайт, с которого перешел. В этом случае Покупатель будет перенаправлен обратно на веб-сайт продавца по ссылке, которая была указана в личном кабинете Продавца в качестве возвратной. Если покупатель выбрал валюту для оплаты, то отправляется запрос на получение адреса и переход на следующую страницу.
- Страница выбранной валюты платежа. Покупателю отображается адрес, на который он должен перевести средства, сумма платежа и сгенерированный qr-код для оплаты. Как только адрес был сгенерирован, запускается обратный отсчет времени, в течение которого Покупатель может совершить платеж (60 минут). Если средства не были получены за указанный промежуток времени, то платеж считается истекшим, необходимо вернуться обратно на сайт Продавца и повторить запрос. Покупатель может вернуться назад к выбору валют, но если средства были отправлены на 1 из сгенерированных адресов, то Merchant начинает отслеживать процесс их получения через сеть и выбор валют становится недоступным.
- Страница ожидания платежа. Как только в Merchant появляется информация о входящей транзакции на указанный адрес, таймер останавливается и появляется лоадер — ожидается необходимое количество подтверждений для успешного завершения платежа.
- Страница успешного платежа. Как только необходимое количество подтверждений было набрано, платеж считается успешно завершенным, средства зачисляются на указанный адрес. Покупатель перенаправляется обратно на сайт Продавца, Продавцу отправляется уведомление об успешном платеже по указанной в личном кабинете ссылке.
- Страница доплаты. Если Покупатель отправил сумму, недостаточную для успешного завершения платежа, то она будет зачислена на указанный адрес, а оставшаяся часть будет отображена на странице доплаты. Таймер ожидания платежа запускается снова, на внесение оставшейся суммы отводится 23 часа. Если платеж не был закрыт в течение указанного времени, то он считается истекшим.
- Страница истекшего платежа. Если Покупатель не внес средства на указанный адрес в течение указанного времени, то платеж переходит в статус истекшего, а Покупатель видит соответствующую страницу с информацией о том, что выданный ему адрес больше не действителен. Так же на странице отображаются контактные данные Продавца, указанные в личном кабинете и кнопка для возврата на сайт Продавца.
Если средства были отправлены, но в Merchant они не были получены за указанный промежуток времени и платеж перешёл в истекшие, Покупателю необходимо обратиться напрямую к Продавцу по указанным контактам.
Мы настоятельно рекомендуем разместить на сайте Продавца информацию о времени, отведенном для перевода средств, во избежание просрочки по сгенерированным платежам.
Все переведенные Покупателем средства зачисляются на баланс Продавца в личном кабинете Merchant в соответствующих криптовалютах. Продавец может вывести средства на свой криптовалютный кошелек, или обменять их на бирже Cryptex на фиатные средства и вывести любым из доступных способов.
Вопросы, связанные с возвратом средств, Покупатель решает напрямую через сайт Продавца и по контактам, указанным в личном кабинете Merchant.
Возможные статусы платежей
- Если оплат по платежу не было, то статус платежа Создан.
- Если есть неподтвержденные сетью транзакции в пути — статус переходит в В работе.
- Если есть подтверждённые оплаты, оплаты в пути отсутствуют, но суммы не хватает, то выставляется статус Дополнительный платеж. При выставлении данного статуса, время для доплаты увеличивается до 24 часов.
- Если подтверждённых оплат хватает, то статус переходит в Закрыт.
- Если по истечении времени, отведенного на оплату, не была получена достаточная сумма для закрытия платежа, статус переходит в Просрочен.
Описание запросов API
1. Создание платежа
POST https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/
Тело запроса
Param | Type | Description |
|---|---|---|
shop* | string($uuid) | Ключ магазина, присвоенный на платформе Сryptex |
currency* | string | Валюта (фиат), в которой создается платеж (в настоящее время только USD) |
amount* | string($decimal) | Сумма платежа в валюте currency |
order_id* | string(pattern: ^[\w-]{1,30}$) | ID заказа в магазине |
details | string | Дополнительная информация |
* — обязательные поля
Ответ
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор созданного платежа |
shop | string($uuid) | Ключ магазина, присвоенный на платформе Сryptex |
amount | string($decimal) | Сумма платежа в валюте currency |
order_id | string(pattern: ^[\w-]{1,30}$) | ID заказа в магазине |
details | string | Дополнительная информация |
Пример
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": "98eaf08f-374d-40ee-92e7-4754f6a5bd48",
"amount": "664.000",
"details": "string",
"order_id": "jajf9999djd"
}
2. Получение детальной информации о платеже
GET https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/{payment_id}
Параметры
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор платежа |
Ответ
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор созданного платежа |
shop | string($uuid) | Информация о магазине |
order_id | string(pattern: ^[\w-]{1,30}$) | ID заказа в магазине |
status | string | Статус платежа |
amount_usd | string | Сумма платежа в фиате при создании |
amount_crypto | number | Сумма платежа в криптовалюте, исходя из курса |
amount_crypto_paid | number | Сумма в криптовалюте, оплаченная и подтвержденная сетью по платежу |
amount_crypto_remaining | number | Сумма в криптовалюте, которую необходимо оплатить |
details | object | Информация о валюте оплаты, адресе и курсе |
deposits | array of objects | Информация транзакции: txid, сумма, статус и количество подтверждений сети |
time_to_expire | number | Время до истечения платежа в секундах |
created_at | string($date-time) | Дата создания |
payment_time | object | Время, отведенное для платежа, в минутах |
Пример
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": {
"name": "my shop",
"success_url": "https://example.com",
"shop_url": "https://example.com",
"accepted_currencies": [
{
"name": "LTC",
"full_name": "Litecoin",
"logo": null,
"deposit_time": 10
},
{
"name": "BTC",
"full_name": "Bitcoin",
"logo": "https://merchant.ctuptex.net/api/v2/merchant/merchant-currency/currency_logos/some_logo.png",
"deposit_time": 40
}
],
"contacts": [
{
"contact_type": "Email",
"contact": "abc@mail.com"
},
{
"contact_type": "Telegram",
"contact": "@some"
},
{
"contact_type": "Jabber",
"contact": "some_jid"
}
]
},
"order_id": "jajf9999djd",
"status": "Created",
"amount_usd": "664.000",
"amount_crypto": 2.73251029,
"amount_crypto_paid": 2.5,
"amount_crypto_remaining": 0.23251029,
"details": {
"name": "LTC",
"full_name": "Litecoin",
"address": "08jwiodkjvoiwdj0",
"qr_code": null,
"course": "243.00"
},
"deposits": [
{
"amount": "2.50000000",
"status": "Closed",
"txid": null,
"confirmations": 0
}
],
"withdrawal": null,
"time_to_expire": 0,
"created_at": "2021-12-10T12:53:18.098141+03:00",
"payment_time": 60
}
3. Генерация крипто-адреса для платежа
POST https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/{payment_id}/get_address/
Параметры
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор платежа |
Тело запроса
Param | Type | Description |
|---|---|---|
currency | string | Буквенный код валюты из списка возможных для оплаты криптовалют |
Ответ
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор созданного платежа |
shop | string($uuid) | Информация о магазине |
order_id | string(pattern: ^[\w-]{1,30}$) | ID заказа в магазине |
status | string | Статус платежа |
amount_usd | string | Сумма платежа в фиате при создании |
amount_crypto | number | Сумма платежа в криптовалюте, исходя из курса |
amount_crypto_paid | number | Сумма в криптовалюте, оплаченная и подтвержденная сетью по платежу |
amount_crypto_remaining | number | Сумма в криптовалюте, которую необходимо оплатить |
details | object | Информация о валюте оплаты, адресе и курсе. |
deposits | array of objects | Информация транзакции: txid, сумма, статус и количество подтверждений сети. |
time_to_expire | number | Время до истечения платежа в секундах |
created_at | string($date-time) | Дата создания |
payment_time | object | Время, отведенное для платежа, в минутах |
Пример
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": {
"name": "my shop",
"success_url": "https://example.com",
"shop_url": "https://example.com",
"accepted_currencies": [
{
"name": "LTC",
"full_name": "Litecoin",
"logo": null,
"deposit_time": 10
},
{
"name": "BTC",
"full_name": "Bitcoin",
"logo": "https://merchant.cryptex.net/api/v2/merchant/merchant-currency/currency_logos/some_logo.png",
"deposit_time": 40
}
],
"contacts": [
{
"contact_type": "Email",
"contact": "abc@mail.com"
},
{
"contact_type": "Telegram",
"contact": "@some"
},
{
"contact_type": "Jabber",
"contact": "some_jid"
}
]
},
"order_id": "jajf9999djd",
"status": "Created",
"amount_usd": "664.000",
"amount_crypto": 2.73251029,
"amount_crypto_paid": 2.5,
"amount_crypto_remaining": 0.23251029,
"details": {
"name": "LTC",
"full_name": "Litecoin",
"address": "08jwiodkjvoiwdj0",
"qr_code": null,
"course": "243.00"
},
"deposits": [
{
"amount": "2.50000000",
"status": "Closed",
"txid": null,
"confirmations": 0
}
],
"withdrawal": null,
"time_to_expire": 0,
"created_at": "2021-12-10T12:53:18.098141+03:00",
"payment_time": 60
}
Хуки
После успешного получения оплаты от клиента, на webhook_success_url магазина будет отправлен POST запрос с детальной информацией о платеже.
Тело запроса
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Идентификатор платежа |
orderId | string | ID заказа в магазине |
status | string | Статус платежа |
currency | string | Буквенный код валюты из списка возможных для оплаты криптовалют |
amount | string($decimal) | Сумма платежа в криптовалюте |
amountUsd | string($decimal) | Сумма платежа в фиате |
rate | string($uuid) | Курс приема платежа |
createdAt | timestamp | Дата создания платежа |
closedAt | timestamo | Дата закрытия платежа |
ВАЖНО! После получения хуки необходимо запросить информацию о платеже через /api/v2/merchant/merchant-invoices/{payment_id}, т.к. запрос на хук может быть подделан!