Создание платежа

post
https://api.cryptomus.com/v1/payment
копировать

Запрос

Параметры запроса

ИмяТип параметраЗначение по умолчаниюОписание
amount*stringСумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28
currency*stringКод валюты
order_id*stringmin: 1max: 128alpha_dashИдентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.
networkstringnullСетевой код блокчейна
url_returnstringmin: 6max: 255urlnullПеред оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.
url_successstringmin: 6max: 255urlnullПосле успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.
url_callbackstringmin: 6max: 255urlnullURL, на который будут отправлены веб-ссылки со статусом оплаты
is_payment_multiplebooleantrueРазрешено ли пользователю оплатить оставшуюся сумму. Это полезно, когда пользователь оплатил не всю сумму счета за одну транзакцию, и вы хотите разрешить ему оплатить полную сумму. Если вы отключите эту функцию, выставление счета завершится после получения первого платежа, и вы получите средства на свой баланс.
lifetimeintegermin: 300max: 432003600Срок действия выставленного счета-фактуры (в секундах)
to_currencystringПараметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC:
amount: 20
currency: USD
to_currency: BTC
API конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты.
subtractintegermin: 0max: 1000Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США.
accuracy_payment_percentnumericmin: 0max: 50Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс
additional_datastringmax: 255nullДополнительная информация для Вас (не показывается клиенту)
currenciesarrayИспользуется массив доступных валют из настроек вашего продавца (если параметр не задан, по умолчанию используются все поддерживаемые криптовалюты).Доступные валюты указаны в разделе настроек продавца.Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура
except_currenciesarraynullСписок исключенных валют для оплаты Структура
course_sourcestringmin: 4max: 20Доступные значенияBinanceBinanceP2PExmoKucoinЕсли не задано, используются обменные курсы Cryptomus.Сервис, из которого берутся обменные курсы для пересчета в счете-фактуре.
from_referral_codestringnullПродавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Cryptomus API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.
Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Cryptomus, и вы будете получать доход от их оборота.
discount_percentintegermin: -99max: 100nullПоложительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5
Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.
Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.
is_refreshbooleanfalseИспользуя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным 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: BTC
API конвертирует сумму в размере 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Сетевой код блокчейна

Описание

Код валюты

Описание

Сетевой код блокчейна

* - обязательный параметр

Счет-фактура будет содержать конкретную криптовалюту и адрес на момент создания только в том случае, если валюта или параметр to_currency является криптовалютой и передан параметр сети (или криптовалюта имеет только одну сеть, например BTC).

Пример запроса

Ниже приведен простой пример с минимально необходимым количеством параметров. В этом случае будет создан счет-фактура в фиатной валюте 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"
}'
копировать

Ответ

Параметры отклика

ИмяОписание
uuiduuid счета-фактуры
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Статус платежа Все статусы платежей
urlURL платежной страницы
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}
копировать