Створення рахунку -фактури
Прохання
Параметри запиту
| Назва | Тип параметра | Значення за замовчуванням | Визначення |
|---|---|---|---|
| amount* | string | - | Сума, яку потрібно сплатити.Якщо в сумі є копійки, тоді надішліть їх із сепаратором "." Приклад: 10.28 |
| currency* | string | - | Валютний код |
| order_id* | stringmin: 1max: 100alpha_dash | - | Ідентифікатор замовлення у вашій системіПараметр повинен бути рядок, що складається з алфавітних символів, цифр, підкреслення та тире. Він не повинен містити жодних пробілів чи спеціальних символів. order_id повинен бути унікальним у торгових рахунках/статичних гаманцях/рецидивахКоли ми знайдемо існуючу рахунок -фактуру з order_id , ми повертаємо його деталі, новий рахунок -фактура не буде створено. |
| network | string | null | Мережевий код Blockchain |
| url_return | stringmin: 6max: 255url | null | Перш ніж платити, користувач може натиснути кнопку на формі платежу та повернутися на сторінку магазину на цій URL -адресі. |
| url_success | stringmin: 6max: 255url | null | Після успішної оплати користувач може натиснути кнопку на платіжній формі та повернутися до цієї URL -адреси. |
| url_callback | stringmin: 6max: 255url | null | URL, на який будуть надсилатися webhooks зі статусом платежу |
| is_payment_multiple | boolean | true | Чи дозволяється користувачеві платити суму, що залишилася. Це корисно, коли користувач не заплатив всю суму рахунку -фактури за одну транзакцію, і ви хочете дозволити йому сплатити до повної суми. Якщо ви вимкнете цю функцію, рахунок -фактура завершиться після отримання першого платежу, і ви отримаєте кошти на свій баланс. |
| lifetime | integermin: 300max: 43200 | 3600 | Життя випущеного рахунку -фактури (за лічені секунди) |
| to_currency | string | - | Параметр використовується для визначення цільової валюти для перетворення суми рахунків -фактур. Створюючи рахунок -фактуру, ви надаєте суму та валюту, а API перетворить цю суму в еквівалентне значення в to_currency.Наприклад, створити рахунок -фактуру за 20 USD в біткойні: amount: 20 currency: USD to_currency : btcAPI перетворить суму 20 USD в його еквівалент у BTC на основі поточного обмінного курсу, і користувач заплатить у BTC to_currency завжди має бути кодом криптовалюти, а не кодом фіатної валюти. |
| subtract | integermin: 0max: 100 | 0 | Відсоток платіжної комісії, що стягується клієнтуЯкщо у вас є ставка 1%, то якщо ви створите рахунок -фактуру за 100 USDT з відніманням = 100 (клієнт платить 100% комісії), клієнту доведеться заплатити 101 USDT. |
| accuracy_payment_percent | numericmin: 0max: 5 | 0 | Прийнятна неточність в оплаті.Наприклад, якщо ви пройдете вартість 5, рахунок -фактура буде позначений як оплачений, навіть якщо клієнт заплатив лише 95% від суми.Фактична сума оплати буде зарахована на залишок |
| additional_data | stringmax: 255 | null | Додаткова інформація для вас (не показана клієнту) |
| currencies | array | Використовується масив доступних валют з налаштувань торговця (якщо параметр не встановлений, всі підтримувані криптовалюти використовуються за замовчуванням).Наявні валюти встановлені в розділі «Купець». | Список дозволених валют для оплати. Це корисно, якщо ви хочете обмежити список монет, які можуть використовувати ваші клієнти для оплати рахунків. Структура |
| except_currencies | array | null | Список виключених валют для оплати Структура |
| from_referral_code | string | null | Торговець, який робить запит, підключається до реферату за кодом.Наприклад, ви - додаток, який генерує рахунки -фактури через API Cryptomus, а ваші клієнти - інші магазини. Вони вводять свій ключ API та ідентифікатор торговця у вашій заявці, і ви надсилаєте запити з їх обліковими повідомленнями та передаючи свій реферальний код.Таким чином, ваші клієнти стають рефералами на вашому обліковому записі Cryptomus, і ви отримаєте дохід від їх обороту. |
| discount_percent | integermin: -99max: 90 | null | Позитивні числа: дозволяє встановити знижку. Щоб встановити знижку на 5% для платежу, слід передати вартість: 5Негативні числа: дозволяє встановити спеціальну додаткову комісію.Щоб встановити додаткову комісію в розмірі 10% для оплати, слід передати вартість: -10Відсоток знижок при створенні рахунку -фактури враховується лише в тому випадку, якщо рахунок -фактура має конкретну криптовалюту. |
| is_refresh | boolean | false | Використовуючи цей параметр, ви можете оновити термін експлуатації та отримати нову адресу для рахунку -фактури, якщо термін експлуатації закінчився.Для цього вам потрібно прийняти всі необхідні параметри, а рахунок -фактура з пропущеним order_id буде оновлена.Змінено лише address, payment_status та expired_at . Жодних інших полів не змінюється, незалежно від переданих параметрів. |
Тип параметра
stringВизначення
Сума, яку потрібно сплатити.Якщо в сумі є копійки, тоді надішліть їх із сепаратором "."
Приклад: 10.28Тип параметра
stringВизначення
Валютний кодТип параметра
stringmin: 1max: 100alpha_dashВизначення
Ідентифікатор замовлення у вашій системіПараметр повинен бути рядок, що складається з алфавітних символів, цифр, підкреслення та тире. Він не повинен містити жодних пробілів чи спеціальних символів. order_id повинен бути унікальним у торгових рахунках/статичних гаманцях/рецидивахКоли ми знайдемо існуючу рахунок -фактуру з order_id , ми повертаємо його деталі, новий рахунок -фактура не буде створено.Тип параметра
stringЗначення за замовчуванням
nullВизначення
Мережевий код BlockchainТип параметра
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 в біткойні:
amount: 20
currency: USD
to_currency : btcAPI перетворить суму 20 USD в його еквівалент у BTC на основі поточного обмінного курсу, і користувач заплатить у BTC to_currency завжди має бути кодом криптовалюти, а не кодом фіатної валюти.Тип параметра
integermin: 0max: 100Значення за замовчуванням
0Визначення
Відсоток платіжної комісії, що стягується клієнтуЯкщо у вас є ставка 1%, то якщо ви створите рахунок -фактуру за 100 USDT з відніманням = 100 (клієнт платить 100% комісії), клієнту доведеться заплатити 101 USDT.Тип параметра
numericmin: 0max: 5Значення за замовчуванням
0Визначення
Прийнятна неточність в оплаті.Наприклад, якщо ви пройдете вартість 5, рахунок -фактура буде позначений як оплачений, навіть якщо клієнт заплатив лише 95% від суми.Фактична сума оплати буде зарахована на залишокТип параметра
stringmax: 255Значення за замовчуванням
nullВизначення
Додаткова інформація для вас (не показана клієнту)Тип параметра
arrayЗначення за замовчуванням
Використовується масив доступних валют з налаштувань торговця (якщо параметр не встановлений, всі підтримувані криптовалюти використовуються за замовчуванням).Наявні валюти встановлені в розділі «Купець».Визначення
Список дозволених валют для оплати. Це корисно, якщо ви хочете обмежити список монет, які можуть використовувати ваші клієнти для оплати рахунків. СтруктураТип параметра
arrayЗначення за замовчуванням
nullТип параметра
stringЗначення за замовчуванням
nullВизначення
Торговець, який робить запит, підключається до реферату за кодом.Наприклад, ви - додаток, який генерує рахунки -фактури через API Cryptomus, а ваші клієнти - інші магазини.
Вони вводять свій ключ API та ідентифікатор торговця у вашій заявці, і ви надсилаєте запити з їх обліковими повідомленнями та передаючи свій реферальний код.Таким чином, ваші клієнти стають рефералами на вашому обліковому записі Cryptomus, і ви отримаєте дохід від їх обороту.Тип параметра
integermin: -99max: 90Значення за замовчуванням
nullВизначення
Позитивні числа:
дозволяє встановити знижку.
Щоб встановити знижку на 5% для платежу, слід передати вартість: 5Негативні числа:
дозволяє встановити спеціальну додаткову комісію.Щоб встановити додаткову комісію в розмірі 10% для оплати, слід передати вартість: -10Відсоток знижок при створенні рахунку -фактури враховується лише в тому випадку, якщо рахунок -фактура має конкретну криптовалюту.Тип параметра
booleanЗначення за замовчуванням
falseВизначення
Використовуючи цей параметр, ви можете оновити термін експлуатації та отримати нову адресу для рахунку -фактури, якщо термін експлуатації закінчився.Для цього вам потрібно прийняти всі необхідні параметри, а рахунок -фактура з пропущеним order_id буде оновлена.Змінено лише address, payment_status та expired_at . Жодних інших полів не змінюється, незалежно від переданих параметрів.
* - обов'язковий параметр
Структура Валюти
| Назва | Визначення |
|---|---|
| currency* | Валютний код |
| network | Мережевий код Blockchain |
Визначення
Валютний кодВизначення
Мережевий код Blockchain
* - обов'язковий параметр
Структура except_currencies
| Назва | Визначення |
|---|---|
| currency* | Валютний код |
| network | Мережевий код Blockchain |
Визначення
Валютний кодВизначення
Мережевий код Blockchain
* - обов'язковий параметр
Приклад запиту
Нижче наведено зразок прикладу з мінімальною необхідною кількістю параметрів. У цьому випадку рахунок -фактура буде створена з фіатною валютою доларів США. На сторінці оплати користувач зможе вибрати криптовалюту та мережу для оплати цього рахунку.
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 | string | Рахунок -фактура UUID |
| order_id | string|null | Ідентифікатор замовлення у вашій системі |
| amount | string | Кількість рахунку -фактури |
| payment_amount | string|null | Сума, сплачена клієнтом |
| payment_amount_usd | string|null | Сума, фактично сплачена клієнтом у доларах США |
| payer_amount | string|null | Сума в payer_currency , яку повинен сплатити клієнт, включаючи знижку або додаткову комісію. |
| payer_amount_exchange_rate | string|null | Обмінний курс, що застосовувався під час здійснення платежу |
| discount_percent | integer|null | Відсоток знижок або додаткової комісії, який був прийнятий у параметрах запиту |
| discount | string | Фактична сума знижки або додаткова комісія з криптовалюти.Наприклад, якщо сума рахунків -фактур становить 15 USDT, а знижка_percent --5, значення знижки --0,75тобто amount + discount = payer_amount |
| payer_currency | string|null | Валюта, в якій замовник повинен здійснити платіж. |
| currency | string | Код валюти рахунку -фактури |
| comments | string|null | Коментар |
| merchant_amount | string|null | Сума в криптовалюті, яка буде зарахована на ваш баланс. Якщо рахунок -фактура сплачується_currency не буде вказана, значення буде нульовим. |
| network | string|null | Мережевий код Blockchain |
| address | string|null | Адреса гаманця для оплати |
| from | string|null | Адреса гаманця, з якого було здійснено платіж |
| txid | string|null | Транзакція хеш |
| payment_status | string | Статус платежу Всі статуси платежів |
| url | string | Сторінка оплати URL -адреси |
| expired_at | integer|null | Тимчасова позначка закінчення рахунку -фактури |
| status | string | Статус платежу Всі статуси платежів |
| is_final | boolean | Чи доопрацьована рахунок -фактура.Коли рахунок -фактура доопрацьовано, неможливо сплатити рахунок -фактуру (він або виплачується, або закінчився) |
| additional_data | string|null | Додаткова інформація |
| created_at | string|null | Дата створення рахунку -фактури. Часовий пояс - UTC+3 |
| updated_at | string|null | Остання дата оновленої рахунку. Часовий пояс - UTC+3 |
| commission | string|null | Сума комісії Cryptomus |
| address_qr_code | string|null | QR-код адреси |
| convert | Інформація про валюту, до якої буде автоматично перетворити платіж. Перетворення виконується з payer_currency до USDTПрисутній, якщо передано convert_currency_code | |
| convert.to_currency | string | Код валюти, до якого буде перетворено платіж |
| convert.commission | string | Плата за конверсію |
| convert.rate | string|null | Обмінний курс |
| convert.amount | string|null | Сума конверсії в to_currency, яка була додана до балансу торговця, з усіма комісіями віднімали. |
| convert_from | Інформація про валюту, з якої було здійснено неправильний платіжПред'явіть, якщо платіж неправильний | |
| convert_from.from_currency | string | Від валюти |
| convert_from.from_amount | string|null | Сума від |
| convert_from.from_network | string|null | Мережевий код Blockchain |
Тип параметра
stringВизначення
Рахунок -фактура UUIDТип параметра
string|nullВизначення
Ідентифікатор замовлення у вашій системіТип параметра
stringВизначення
Кількість рахунку -фактуриТип параметра
string|nullВизначення
Сума, сплачена клієнтомТип параметра
string|nullВизначення
Сума, фактично сплачена клієнтом у доларах СШАТип параметра
string|nullВизначення
Сума в payer_currency , яку повинен сплатити клієнт, включаючи знижку або додаткову комісію.Тип параметра
string|nullВизначення
Обмінний курс, що застосовувався під час здійснення платежуТип параметра
integer|nullВизначення
Відсоток знижок або додаткової комісії, який був прийнятий у параметрах запитуТип параметра
stringВизначення
Фактична сума знижки або додаткова комісія з криптовалюти.Наприклад, якщо сума рахунків -фактур становить 15 USDT, а знижка_percent --5, значення знижки --0,75тобто amount + discount = payer_amountТип параметра
string|nullВизначення
Валюта, в якій замовник повинен здійснити платіж.Тип параметра
stringВизначення
Код валюти рахунку -фактуриТип параметра
string|nullВизначення
КоментарТип параметра
string|nullВизначення
Сума в криптовалюті, яка буде зарахована на ваш баланс. Якщо рахунок -фактура сплачується_currency не буде вказана, значення буде нульовим.Тип параметра
string|nullВизначення
Мережевий код BlockchainТип параметра
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Визначення
Мережевий код Blockchain
Приклад відповіді
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 USDT в мережі 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 Network. Рахунок -фактура матиме адресу на момент створення.
1{
2 "amount": "25",
3 "currency": "USD",
4 "order_id": "1",
5 "to_currency": "USDT",
6 "network": "tron"
7}КопіяЗапитайте дані, щоб створити рахунок -фактуру для 20 USDT та дозволити клієнтам платити у всіх доступних мережах
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}КопіяPayments.If we don’t support the currency code you provided in currency parameter
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}Копія