Создание платежа
Запрос
Параметры запроса
Имя | Тип параметра | Значение по умолчанию | Описание |
---|---|---|---|
amount* | string | Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.' Пример: 10.28 | |
currency* | string | Код валюты | |
order_id* | stringmin: 1max: 128alpha_dash | Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет. | |
network | string | null | Сетевой код блокчейна |
url_return | stringmin: 6max: 255url | null | Перед оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL. |
url_success | stringmin: 6max: 255url | null | После успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL. |
url_callback | stringmin: 6max: 255url | null | URL, на который будут отправлены веб-ссылки со статусом оплаты |
is_payment_multiple | boolean | true | Разрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс. |
lifetime | integermin: 300max: 43200 | 3600 | Срок действия выставленного счета-фактуры (в секундах) |
to_currency | string | Параметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC: amount: 20 currency: USD to_currency: BTCAPI конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты. | |
subtract | integermin: 0max: 100 | 0 | Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США. |
accuracy_payment_percent | numericmin: 0max: 5 | 0 | Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс |
additional_data | stringmax: 255 | null | Дополнительная информация для Вас (не показывается клиенту) |
currencies | array | Используется массив доступных валют из настроек вашего продавца (если параметр не задан, по умолчанию используются все поддерживаемые криптовалюты).Доступные валюты указаны в разделе настроек продавца. | Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура |
except_currencies | array | null | Список исключенных валют для оплаты Структура |
course_source | stringmin: 4max: 20Доступные значения• Binance• BinanceP2P• Exmo• Kucoin | Если не задано, используются обменные курсы Cryptomus. | Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре. |
from_referral_code | string | null | Продавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Cryptomus API, а вашими клиентами являются другие магазины. Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Cryptomus, и вы будете получать доход от их оборота. |
discount_percent | integermin: -99max: 100 | null | Положительные числа: Позволяет вам установить скидку. Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5Отрицательные числа: Позволяет вам установить пользовательскую дополнительную комиссию.Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта. |
is_refresh | boolean | false | Используя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров. |
Тип параметра
stringОписание
Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28Тип параметра
stringОписание
Код валютыТип параметра
stringmin: 1max: 128alpha_dashОписание
Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.Тип параметра
stringОписание
Сетевой код блокчейнаТип параметра
stringmin: 6max: 255urlОписание
Перед оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.Тип параметра
stringmin: 6max: 255urlОписание
После успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.Тип параметра
stringmin: 6max: 255urlОписание
URL, на который будут отправлены веб-ссылки со статусом оплатыТип параметра
booleanОписание
Разрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс.Тип параметра
integermin: 300max: 43200Описание
Срок действия выставленного счета-фактуры (в секундах)Тип параметра
stringОписание
Параметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC:
amount: 20
currency: USD
to_currency: BTCAPI конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты.Тип параметра
integermin: 0max: 100Описание
Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США.Тип параметра
numericmin: 0max: 5Описание
Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на балансТип параметра
stringmax: 255Описание
Дополнительная информация для Вас (не показывается клиенту)Тип параметра
arrayОписание
Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. СтруктураТип параметра
arrayОписание
Список исключенных валют для оплаты СтруктураТип параметра
stringmin: 4max: 20
Доступные значения- Binance- BinanceP2P- Exmo- KucoinОписание
Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре.Тип параметра
stringОписание
Продавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Cryptomus API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Cryptomus, и вы будете получать доход от их оборота.Тип параметра
integermin: -99max: 100Описание
Положительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.Тип параметра
booleanОписание
Используя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров.
* - обязательный параметр
Структура Валюты
Имя | Описание |
---|---|
currency* | Код валюты |
network | Сетевой код блокчейна |
Описание
Код валютыОписание
Сетевой код блокчейна
* - обязательный параметр
Структура except_currencies
Имя | Описание |
---|---|
currency* | Код валюты |
network | Сетевой код блокчейна |
Описание
Код валютыОписание
Сетевой код блокчейна
* - обязательный параметр
Пример запроса
Ниже приведен простой пример с минимально необходимым количеством параметров. В этом случае будет создан счет-фактура в фиатной валюте USD. На странице оплаты пользователь сможет выбрать криптовалюту и сеть для оплаты этого счета.
curl https://api.cryptomus.com/v1/payment \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
"amount": "15",
"currency": "USD",
"order_id": "1"
}'
копироватьОтвет
Параметры отклика
Имя | Описание |
---|---|
uuid | uuid счета-фактуры |
order_id | Идентификатор заказа в Вашей системе |
amount | Сумма счета-фактуры |
payment_amount | Сумма, уплаченная клиентом |
payer_amount | Сумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию. |
discount_percent | Процент скидки или дополнительной комиссии, который был передан в параметрах запроса |
discount | Фактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount |
payer_currency | Валюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты. |
currency | Код валюты счета-фактуры |
merchant_amount | Сумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null. |
network | Сетевой код блокчейна |
address | Адрес кошелька для оплаты |
from | Адрес кошелька, с которого был произведен платеж |
txid | Хэш транзакции |
payment_status | Статус платежа Все статусы платежей |
url | URL платежной страницы |
expired_at | Отметка времени истечения срока действия счета-фактуры |
is_final | Завершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек) |
additional_data | Дополнительная информация |
created_at | Дата создания счета-фактуры. Часовой пояс - UTC+3 |
updated_at | Дата последнего обновления счета-фактуры. Часовой пояс - UTC+3 |
Описание
uuid счета-фактурыОписание
Идентификатор заказа в Вашей системеОписание
Сумма счета-фактурыОписание
Сумма, уплаченная клиентомОписание
Сумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию.Описание
Процент скидки или дополнительной комиссии, который был передан в параметрах запросаОписание
Фактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amountОписание
Валюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты.Описание
Код валюты счета-фактурыОписание
Сумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null.Описание
Сетевой код блокчейнаОписание
Адрес кошелька для оплатыОписание
Адрес кошелька, с которого был произведен платежОписание
Хэш транзакцииОписание
Статус платежа Все статусы платежейОписание
URL платежной страницыОписание
Отметка времени истечения срока действия счета-фактурыОписание
Завершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)Описание
Дополнительная информацияОписание
Дата создания счета-фактуры. Часовой пояс - UTC+3Описание
Дата последнего обновления счета-фактуры. Часовой пояс - UTC+3
Пример ответа
1{
2 "state": 0,
3 "result": {
4 "uuid": "26109ba0-b05b-4ee0-93d1-fd62c822ce95",
5 "order_id": "1",
6 "amount": "15.00",
7 "payment_amount": null,
8 "payer_amount": null,
9 "discount_percent": null,
10 "discount": "0.00000000",
11 "payer_currency": null,
12 "currency": "USD",
13 "merchant_amount": null,
14 "network": null,
15 "address": null,
16 "from": null,
17 "txid": null,
18 "payment_status": "check",
19 "url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
20 "expired_at": 1689098133,
21 "status": "check",
22 "is_final": false,
23 "additional_data": null,
24 "created_at": "2023-07-11T20:23:52+03:00",
25 "updated_at": "2023-07-11T21:24:17+03:00"
26 }
27}
копироватьЕще примеры
Запросите данные для создания счета-фактуры на 20 USD в сети tron. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1",
5 "network": "tron"
6}
копироватьЗапросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в любой сети.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT"
6}
копироватьЗапросите данные, чтобы выставить счет на 25 USD и разрешить клиентам оплачивать только USDT в сети tron. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT",
6 "network": "tron"
7}
копироватьЗапросите данные, чтобы выставить счет на 20 USD и позволить клиентам оплачивать во всех доступных сетях
1{
2 "amount": "20",
3 "currency": "USDT",
4 "order_id": "1"
5}
копироватьЗапросите данные, чтобы выставить счет на 20 USD и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "20",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "BTC"
6}
копироватьЗапросите данные, чтобы выставить счет на 0,5 BTC и разрешить клиентам оплачивать только биткоинами. Счет-фактура будет иметь адрес на момент создания.
1{
2 "amount": "0.5",
3 "currency": "BTC",
4 "order_id": "1"
5}
копироватьВозможные ошибки
Ошибки проверки
код : 422
Примеры ответов:
Если какой-то параметр требуется и не передан:
1{
2 "state": 1,
3 "errors": {
4 "amount": ["validation.required"]
5 }
6}
копироватьЕсли вы указали сетевой код, который не поддерживается
1{
2 "state": 1,
3 "message": "The network was not found"
4}
копироватьЕсли мы не поддерживаем код валюты, который вы указали в параметре currency:
1{
2 "state": 1,
3 "message": "The currency was not found"
4}
копироватьЕсли ваши платежи заблокированы. В этом случае вам необходимо обратиться в службу поддержки.
1{
2 "state": 1,
3 "message": "You are forbidden"
4}
копироватьЕсли мы не найдем платежный сервис в валюте, которая была передана в параметре to_currency:
1{
2 "state": 1,
3 "message": "Not found service to_currency"
4}
копироватьЕсли случайно что-то произойдет при преобразовании в to_currency:
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}
копироватьЕсли сумма платежа меньше минимальной поддерживаемой суммы для криптовалюты, вы получите это сообщение об ошибке:
1{
2 "state": 1,
3 "message": "Minimum amount 0.5 USDT"
4}
копироватьЕсли сумма платежа превышает максимальную поддерживаемую сумму для криптовалюты, вы получите это сообщение об ошибке:
1{
2 "state": 1,
3 "message": "Maximum amount 10000000 USDT"
4}
копироватьЕсли у вас не будет активного торгового кошелька с криптовалютой платежа, вы получите эту ошибку:
1{
2 "state": 1,
3 "message": "Wallet not found"
4}
копироватьЕсли происходят технические работы и платеж временно недоступен, вы можете получать следующие сообщения об ошибках:
1{
2 "state": 1,
3 "message": "Gateway error"
4}
копировать
1{
2 "state": 1,
3 "message": "The terminal was not found"
4}
копировать
1{
2 "state": 1,
3 "message": "Server error"
4}
копироватьВнутренняя ошибка сервера
код : 500
Примеры ответов:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}
копировать