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

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

Запрос

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

ИмяТип параметраЗначение по умолчаниюОписание
amount*string-Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28
currency*string-Код валюты
order_id*stringmin: 1max: 100alpha_dash-Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.
networkstringnullСетевой код блокчейна
url_returnstringmin: 6max: 255urlnullПеред оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.
url_successstringmin: 6max: 255urlnullПосле успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.
url_callbackstringmin: 6max: 255urlnullURL, на который будут отправляться webhooks с состоянием платежа
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Список исключенных валют для оплаты Структура
from_referral_codestringnullПродавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Cryptomus API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.
Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Cryptomus, и вы будете получать доход от их оборота.
discount_percentintegermin: -99max: 90nullПоложительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5
Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.
Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.
is_refreshbooleanfalseИспользуя этот параметр, вы можете обновить срок действия и получить новый адрес для счета-фактуры, если срок действия истек.Чтобы сделать это, вам нужно передать все необходимые параметры, и счет-фактура с переданным order_id будет обновлен.Изменены только address, payment_status и expired_at. Никакие другие поля не изменяются, независимо от переданных параметров.

Тип параметра

string

Описание

Сумма, подлежащая выплате.Если в сумме есть пенни, то отправьте их с разделителем '.'
Пример: 10.28

Тип параметра

string

Описание

Код валюты

Тип параметра

stringmin: 1max: 100alpha_dash

Описание

Идентификатор заказа в Вашей системеПараметр должен представлять собой строку, состоящую из буквенных символов, цифр, подчеркиваний и тире. Он не должен содержать никаких пробелов или специальных символов. order_id должен быть уникальным в счетах продавца/статических кошельках/повторных платежахКогда мы находим существующий счет-фактуру с order_id, мы возвращаем его реквизиты, новый счет-фактура создан не будет.

Тип параметра

string

Значение по умолчанию

null

Описание

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

Тип параметра

stringmin: 6max: 255url

Значение по умолчанию

null

Описание

Перед оплатой пользователь может нажать на кнопку в форме оплаты и вернуться на страницу магазина по этому URL.

Тип параметра

stringmin: 6max: 255url

Значение по умолчанию

null

Описание

После успешной оплаты пользователь может нажать на кнопку в форме оплаты и вернуться по этому URL.

Тип параметра

stringmin: 6max: 255url

Значение по умолчанию

null

Описание

URL, на который будут отправляться webhooks с состоянием платежа

Тип параметра

boolean

Значение по умолчанию

true

Описание

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

Тип параметра

integermin: 300max: 43200

Значение по умолчанию

3600

Описание

Срок действия выставленного счета-фактуры (в секундах)

Тип параметра

string

Описание

Параметр используется для указания целевой валюты для пересчета суммы счета. При создании счета-фактуры вы указываете сумму и валюту, и API преобразует эту сумму в эквивалентное значение в to_currency.Например, чтобы создать счет на 20 USD в BTC:
amount: 20
currency: USD
to_currency: BTC
API конвертирует сумму в размере 20 USD в ее эквивалент в BTC на основе текущего обменного курса, и пользователь будет платить в BTC.to_currency всегда должен быть кодом криптовалюты, а не кодом фиатной валюты.

Тип параметра

integermin: 0max: 100

Значение по умолчанию

0

Описание

Процент от комиссии за платеж, взимаемой с клиентаЕсли у вас ставка 1%, то если вы создадите счет на 100 USD с вычитанием = 100 (клиент платит 100% комиссии), клиенту придется заплатить 101 доллар США.

Тип параметра

numericmin: 0max: 5

Значение по умолчанию

0

Описание

Допустимая неточность в оплате.Например, если вы передадите значение 5, счет будет помечен как оплаченный, даже если клиент оплатил только 95% суммы.Фактическая сумма платежа будет зачислена на баланс

Тип параметра

stringmax: 255

Значение по умолчанию

null

Описание

Дополнительная информация для Вас (не показывается клиенту)

Тип параметра

array

Значение по умолчанию

Используется массив доступных валют из настроек вашего продавца (если параметр не задан, по умолчанию используются все поддерживаемые криптовалюты).Доступные валюты указаны в разделе настроек продавца.

Описание

Список разрешенных валют для оплаты. Это полезно, если вы хотите ограничить список монет, которые ваши клиенты могут использовать для оплаты счетов. Структура

Тип параметра

array

Значение по умолчанию

null

Описание

Список исключенных валют для оплаты Структура

Тип параметра

string

Значение по умолчанию

null

Описание

Продавец, который делает запрос, подключается к рефереру с помощью кода.Например, вы являетесь приложением, которое генерирует счета-фактуры через Cryptomus API, а вашими клиентами являются другие магазины.
Они вводят свой api-ключ и идентификатор продавца в ваше приложение, а вы отправляете запросы с их учетными данными и передаете свой реферальный код.
Таким образом, ваши клиенты становятся рефералами на вашем аккаунте Cryptomus, и вы будете получать доход от их оборота.

Тип параметра

integermin: -99max: 90

Значение по умолчанию

null

Описание

Положительные числа:
Позволяет вам установить скидку.
Чтобы установить скидку в размере 5% при оплате, вы должны указать значение: 5
Отрицательные числа:
Позволяет вам установить пользовательскую дополнительную комиссию.
Чтобы установить дополнительную комиссию в размере 10% за платеж, вы должны указать значение: -10Процент скидки при создании счета-фактуры учитывается только в том случае, если в счете указана определенная криптовалюта.

Тип параметра

boolean

Значение по умолчанию

false

Описание

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

Ответ

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

ИмяТип параметраОписание
uuidstringuuid счета-фактуры
order_idstring|nullИдентификатор заказа в Вашей системе
amountstringСумма счета-фактуры
payment_amountstring|nullСумма, уплаченная клиентом
payment_amount_usdstring|nullСумма, фактически уплаченная клиентом в долларах США
payer_amountstring|nullСумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию.
payer_amount_exchange_ratestring|nullКурс обмена, применённый при совершении платежа
discount_percentinteger|nullПроцент скидки или дополнительной комиссии, который был передан в параметрах запроса
discountstringФактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount
payer_currencystring|nullВалюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты.
currencystringКод валюты счета-фактуры
commentsstring|nullКомментарий
merchant_amountstring|nullСумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null.
networkstring|nullСетевой код блокчейна
addressstring|nullАдрес кошелька для оплаты
fromstring|nullАдрес кошелька, с которого был произведен платеж
txidstring|nullХэш транзакции
payment_statusstringСтатус платежа Все статусы платежей
urlstringURL платежной страницы
expired_atinteger|nullОтметка времени истечения срока действия счета-фактуры
statusstringСтатус платежа Все статусы платежей
is_finalbooleanЗавершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)
additional_datastring|nullДополнительная информация
created_atstring|nullДата создания счета-фактуры. Часовой пояс - UTC+3
updated_atstring|nullДата последнего обновления счета-фактуры. Часовой пояс - UTC+3
commissionstring|nullСумма комиссии Cryptomus
address_qr_codestring|nullQR-код адреса
convertИнформация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПрисутствует, если передан параметр convert_currency_code.
convert.to_currencystringКод валюты, в которую будет конвертирован платеж
convert.commissionstringКомиссия за конвертацию
convert.ratestring|nullКоэффициент конверсии
convert.amountstring|nullСумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.
convert_fromИнформация о валюте, из которой был произведен ошибочный платеж.Присутствуйте при неправильной оплате.
convert_from.from_currencystringИз валюты
convert_from.from_amountstring|nullСумма от
convert_from.from_networkstring|nullСетевой код блокчейна

Тип параметра

string

Описание

uuid счета-фактуры

Тип параметра

string|null

Описание

Идентификатор заказа в Вашей системе

Тип параметра

string

Описание

Сумма счета-фактуры

Тип параметра

string|null

Описание

Сумма, уплаченная клиентом

Тип параметра

string|null

Описание

Сумма, фактически уплаченная клиентом в долларах США

Тип параметра

string|null

Описание

Сумма в payer_currency, которую клиент должен оплатить, включая скидку или дополнительную комиссию.

Тип параметра

string|null

Описание

Курс обмена, применённый при совершении платежа

Тип параметра

integer|null

Описание

Процент скидки или дополнительной комиссии, который был передан в параметрах запроса

Тип параметра

string

Описание

Фактическая сумма скидки или дополнительной комиссии в криптовалюте.Например, если сумма счета составляет 15 USD, а discount_percent равен -5, значение скидки будет равно -0,75т.е. amount + discount = payer_amount

Тип параметра

string|null

Описание

Валюта, в которой клиент должен произвести платеж. Если значение равно null, клиент может выбрать конкретную валюту на странице оплаты.

Тип параметра

string

Описание

Код валюты счета-фактуры

Тип параметра

string|null

Описание

Комментарий

Тип параметра

string|null

Описание

Сумма в криптовалюте, которая будет зачислена на ваш баланс. Если не указан параметр invoice payer_currency, значение будет равно null.

Тип параметра

string|null

Описание

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

Тип параметра

string|null

Описание

Адрес кошелька для оплаты

Тип параметра

string|null

Описание

Адрес кошелька, с которого был произведен платеж

Тип параметра

string|null

Описание

Хэш транзакции

Тип параметра

string

Описание

Статус платежа Все статусы платежей

Тип параметра

string

Описание

URL платежной страницы

Тип параметра

integer|null

Описание

Отметка времени истечения срока действия счета-фактуры

Тип параметра

string

Описание

Статус платежа Все статусы платежей

Тип параметра

boolean

Описание

Завершена ли счет-фактура.Когда выставление счета завершено, оплатить счет невозможно (он либо оплачен, либо срок его действия истек)

Тип параметра

string|null

Описание

Дополнительная информация

Тип параметра

string|null

Описание

Дата создания счета-фактуры. Часовой пояс - UTC+3

Тип параметра

string|null

Описание

Дата последнего обновления счета-фактуры. Часовой пояс - UTC+3

Тип параметра

string|null

Описание

Сумма комиссии Cryptomus

Тип параметра

string|null

Описание

QR-код адреса

Описание

Информация о валюте, в которую будет автоматически конвертирован платеж. Конвертация производится из payer_currency в USDTПрисутствует, если передан параметр convert_currency_code.

Тип параметра

string

Описание

Код валюты, в которую будет конвертирован платеж

Тип параметра

string

Описание

Комиссия за конвертацию

Тип параметра

string|null

Описание

Коэффициент конверсии

Тип параметра

string|null

Описание

Сумма конвертации в to_currency, которая была добавлена на баланс продавца, с вычетом всех комиссионных.

Описание

Информация о валюте, из которой был произведен ошибочный платеж.Присутствуйте при неправильной оплате.

Тип параметра

string

Описание

Из валюты

Тип параметра

string|null

Описание

Сумма от

Тип параметра

string|null

Описание

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

Пример ответа


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		"payment_amount_usd": null,
9		"payer_amount": null,
10		"payer_amount_exchange_rate": null,
11		"discount_percent": null,
12		"discount": "0.00000000",
13		"payer_currency": null,
14		"currency": "USD",
15		"comments": null,
16		"merchant_amount": null,
17		"network": null,
18		"address": null,
19		"from": null,
20		"txid": null,
21		"payment_status": "check",
22		"url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
23		"expired_at": 1689098133,
24		"status": "check",
25		"is_final": false,
26		"additional_data": null,
27		"created_at": "2023-07-11T20:23:52+03:00",
28		"updated_at": "2023-07-11T21:24:17+03:00",
29		"commission": null,
30		"address_qr_code": null
31	}
32}
Скопировать

Еще примеры

Запросите данные для создания счета-фактуры на 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}
Скопировать