Documentation Index
Fetch the complete documentation index at: https://docs.crypto-cash.world/llms.txt
Use this file to discover all available pages before exploring further.
Fiat Module
Примітка: усі числові значення, суми, курси та ідентифікатори в прикладах є ілюстративними та наведені лише для демонстрації. Реальні значення залежать від ринкових умов, конфігурації акаунта та параметрів конкретної транзакції.
Огляд
Fiat Module — це підсистема платформи CryptoCash, яка дозволяє мерчанту приймати фіатні платежі від кінцевих користувачів і отримувати криптовалюту на свій гаманець.
Інтеграція виконується через підписані API-запити. Платежі проводяться через платіжного провайдера (Mercuryo). Кінцевий користувач завершує оплату у віджеті CryptoCash, де вибирає спосіб оплати. Після обробки платежу мерчант отримує webhook із фінальним статусом.
Підтримувані можливості:
- Оплата карткою, Apple Pay, Google Pay, SEPA та інші способи оплати
- Підписані запити (
ED25519 або LEGACY/SHA256) для автентифікації мерчанта
- Webhook-и мерчанту при кожній зміні статусу транзакції
- Автоматичний розрахунок заробітку мерчанта на основі
partner_fee
Високорівневий сценарій
1. Мерчант надсилає підписаний API-запит → отримує URL для оплати
2. Користувач відкриває URL → бачить віджет CryptoCash
3. Користувач вибирає спосіб оплати
4. Платіжний провайдер обробляє платіж
5. Мерчант отримує webhook при кожній зміні статусу
6. Після успішної оплати автоматично розраховується заробіток мерчанта
| Спосіб оплати | Сценарій |
|---|
| Apple Pay (native) | Користувач оплачує прямо у віджеті — без редиректу на зовнішню сторінку |
| Картка / інші способи | Користувач редиректиться на сторінку платіжного провайдера для завершення оплати |
Налаштування мерчанта та Fiat API Key
Що налаштовує мерчант
Після того як адміністратор підготував акаунт, мерчант генерує Fiat API Key в особистому кабінеті. Під час створення ключа задаються параметри, які застосовуються до всіх платежів, пов’язаних із цим ключем:
| Параметр | Опис |
|---|
keyType | Алгоритм підпису: ED25519 (рекомендовано) або LEGACY (SHA256) |
keyName | Довільна назва ключа |
partnerFee | Частка комісії провайдера, яка йде мерчанту; налаштовується адміністратором на provider-акаунті |
paymentMethods | Способи оплати, доступні у віджеті (наприклад, ["card", "apple_pay"]) |
webhookUrl | URL для отримання webhook про статуси платежів |
logoUrl | Логотип мерчанта, що відображається у віджеті |
ipRestrictionEnabled | Чи обмежувати API-доступ за IP-адресою |
allowedIpAddresses | Список дозволених IP-адрес або CIDR-діапазонів |
expiresAt | Конкретна дата закінчення дії ключа |
neverExpires | Якщо true, ключ не закінчується (expiresAt = null); за замовчуванням строк дії ключа — 1 рік |
publicKey / privateKey. Приватний ключ зберігається на платформі в зашифрованому вигляді та показується мерчанту лише один раз — під час створення. Збережіть його одразу.
Якщо на акаунті мерчанта увімкнена двофакторна автентифікація, для генерації ключа знадобиться підтвердження 2FA.
Поля Fiat API Key
| Поле | Тип | Опис | |
|---|
publicKey | string | Ідентифікатор ключа, передається в кожному запиті | |
privateKey | string | Секрет для підпису запитів; на платформі зберігається зашифрованим | |
keyType | ED25519 | LEGACY | Алгоритм підпису |
isActive | boolean | Чи активний ключ | |
expiresAt | datetime | null | Час закінчення дії (null — без строку) |
paymentMethods | string[] | Дозволені способи оплати | |
webhookUrl | string | null | URL для доставки webhook |
logoUrl | string | null | URL логотипа |
ipRestrictionEnabled | boolean | Чи увімкнене обмеження за IP | |
allowedIpAddresses | string[] | Дозволені IP-адреси | |
ED25519 vs LEGACY
| ED25519 | LEGACY |
|---|
| Алгоритм | Асиметрична криптографія (Ed25519) | Підпис на основі SHA256 |
| Зв’язок ключів | publicKey математично виводиться з privateKey | publicKey — ідентифікатор; privateKey — спільний секрет, що використовується під час підпису |
| Верифікація | Підпис перевіряється за publicKey без знання privateKey | Платформа використовує збережений privateKey для перевірки підпису |
| Рекомендовано | Так | Лише для сумісності зі старими інтеграціями |
Що перевіряється при кожному запиті
Під час отримання підписаного запиту платформа перевіряє:
- Ключ активний
- Строк дії ключа не закінчився
- IP API-викликача (сервер мерчанта) входить до списку дозволених, якщо увімкнене обмеження за IP
- Підпис валідний для вибраного алгоритму
Важливо: обмеження за IP застосовується до адреси сервера, який робить API-запит, а не до IP кінцевого користувача в полі ip payload-а платежу.
Підписані запити
Усі API-запити мерчанта мають бути підписані. Алгоритм підпису визначається значенням keyType, вибраним під час створення ключа.
Структура запиту
{
"data": "<base64-encoded JSON payload>",
"signature": "<base64-encoded signature>"
}
publicKey передається або в заголовку x-public-key, або всередині об’єкта data. Якщо присутні обидва, пріоритет має заголовок.
ED25519 (рекомендовано)
1. payload → JSON.stringify(payload)
2. json → Buffer.from(json, 'utf8').toString('base64') → data
3. sign → Ed25519.sign(Buffer.from(data), privateKeyBytes) → signatureBytes
4. signature → signatureBytes.toString('base64')
LEGACY (SHA256)
1. payload → JSON.stringify(payload)
2. json → Buffer.from(json, 'utf8').toString('base64') → data
3. hash → SHA256(privateKey + data) → hashHex
4. signature → Buffer.from(hashHex, 'utf8').toString('base64')
Повний приклад
Payload для form/retrieve:
{
"publicKey": "a1b2c3d4...",
"fiatCurrency": "SGD",
"fiatAmount": "100",
"currency": "USDT",
"network": "TRC20",
"address": "TXxxx...",
"ip": "203.0.113.5"
}
{
"data": "eyJwdWJsaWNLZXkiOiJhMWIyYzNkNC4uLiIsImZpYXRDdXJyZW5jeSI6IlNHRCIsImZpYXRBbW91bnQiOiIxMDAiLCJjdXJyZW5jeSI6IlVTRFQiLCJuZXR3b3JrIjoiVFJDMjAiLCJhZGRyZXNzIjoiVFh4eHguLi4iLCJpcCI6IjIwMy4wLjExMy41In0=",
"signature": "base64-encoded-signature"
}
Endpoint
POST https://buy.crypto-cash.world/merchant/api/v1/pay-fiat/form/retrieve
Запит
Поле data підписаного запиту містить такий JSON:
| Поле | Тип | Обов’язкове | Опис |
|---|
ticker | string | ✓* | Тикер криптоактиву та мережі (наприклад, "USDTTRC20") |
currency | string | ✓* | Код криптовалюти (наприклад, "USDT") |
network | string | ✓* | Мережа блокчейну (наприклад, "TRC20") |
fiatCurrency | string | ✓ | Код фіатної валюти (наприклад, "SGD") |
fiatAmount | string | ✓ | Сума у фіаті як рядок (наприклад, "100") |
address | string | ✓ | Адреса гаманця для зарахування криптовалюти |
ip | string | ✓ | IP-адреса кінцевого користувача |
email | string | — | E-mail клієнта |
redirectUrl | string | — | URL, на який потрібно повернути користувача після оплати |
lang | string | — | Мова віджета (за замовчуванням "en") |
externalId | string | — | Зовнішній ID замовлення на стороні мерчанта (має бути унікальним у межах ключа) |
* Щоб вибрати криптоактив, передайте або ticker, або пару currency + network.
Відповідь
{
"code": 200,
"data": {
"item": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "order-123",
"url": "https://buy.cryptocash.world/merchant/payment/550e8400-e29b-41d4-a716-446655440000"
}
}
}
| Поле | Опис |
|---|
id | Внутрішній UUID транзакції |
externalId | Зовнішній ID із запиту або null |
url | URL віджета CryptoCash — на нього потрібно перенаправити користувача |
Що відбувається після запиту
- Перевіряється підпис та IP.
- Перевіряється унікальність
externalId у межах ключа мерчанта.
- Сума у фіаті звіряється з мінімально допустимою для вибраної валюти.
- Значення
network нормалізується (без урахування регістру).
- Створюється транзакція зі статусом
New.
- Генерується URL віджета.
- Мерчанту надсилається webhook
payment::created.
- Повертаються
id і url.
Віджет CryptoCash і сторінка провайдера
| Віджет CryptoCash | Сторінка платіжного провайдера |
|---|
| URL | https://buy.cryptocash.world/merchant/payment/{id} | Генерується всередині віджета |
| Брендинг | Логотип мерчанта | Стилістика провайдера |
| Призначення | Вибір способу оплати, прев’ю курсу, native Apple Pay | Пряма обробка платежу |
Публічне API мерчанта
Отримання платежу
POST https://buy.cryptocash.world/merchant/api/v1/pay-fiat/payments/retrieve
data містить одне з:
{ "internalId": "550e8400-..." }
{ "externalId": "order-123" }
{
"code": 200,
"data": {
"item": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "order-123",
"status": "Paid",
"fiatCurrency": "SGD",
"fiatAmount": "100",
"cryptoCurrency": "USDT",
"network": "TRC20",
"cryptoAmount": "73.21",
"address": "TXxxx...",
"hash": "blockchain-hash",
"widgetUrl": "https://buy.cryptocash.world/merchant/payment/550e8400-...",
"createdAt": "2026-04-16T10:00:00.000Z",
"updatedAt": "2026-04-16T10:07:00.000Z"
}
}
}
Список платежів
POST https://buy.cryptocash.world/merchant/api/v1/pay-fiat/payments/list
data:
| Поле | Тип | За замовчуванням | Опис |
|---|
page | number | 1 | Номер сторінки |
pageSize | number | 100 | Кількість елементів на сторінці |
dateAfter | datetime | — | Фільтр: створено після цієї дати |
dateBefore | datetime | — | Фільтр: створено до цієї дати |
{
"code": 200,
"data": {
"items": [ /* масив платежів у тій самій структурі, що й retrieve */ ],
"pagination": {
"page": 1,
"pageSize": 100,
"total": 42
}
}
}
Списки валют
POST https://buy.cryptocash.world/merchant/api/v1/fiat-currencies/list
POST https://buy.cryptocash.world/merchant/api/v1/pay-fiat/crypto-currencies/list
data:
crypto-currencies/list повертає доступні мерчанту криптовалюти разом із мережами та тикерами. Значення з tickers можна передавати в form/retrieve замість пари currency + network.
Поля відповіді платежу
| Поле | Тип | Nullable | Опис |
|---|
id | string | | UUID транзакції |
externalId | string | ✓ | Зовнішній ID мерчанта |
status | string | | Поточний статус |
fiatCurrency | string | | Код фіатної валюти |
fiatAmount | string | | Сума у фіаті |
cryptoCurrency | string | | Код криптовалюти |
network | string | | Мережа блокчейну |
cryptoAmount | string | ✓ | Отримана сума в крипто |
address | string | | Адреса гаманця |
hash | string | ✓ | Хеш транзакції в блокчейні |
widgetUrl | string | ✓ | URL віджета |
createdAt | datetime | | Час створення |
updatedAt | datetime | | Час останнього оновлення |
Статуси транзакцій
| Статус | Опис |
|---|
New | Транзакцію створено, очікуються дії користувача |
Waiting | Платіж прийнято та обробляється |
Paid | Криптовалюту відправлено на адресу гаманця |
Fail | Платіж завершився неуспішно |
Canceled | Платіж скасовано |
Обробка помилок
Усі помилки API повертаються в одному з двох форматів:
Формат A — кодована помилка:
{ "code": 2020, "message": "..." }
Коди помилок
| Код | Опис |
|---|
1000 | Bad request |
1102 | Невалідний запит (непідтримувана мережа, сума нижче мінімальної, дублювання externalId) |
1110 | Помилка валідації запиту |
2010 | Помилка декодування data |
2011 | Помилка декодування signature |
2020 | Невірний підпис |
2021 | API key заблоковано |
2030 | IP-адресу заборонено |
3001 | Замовлення не знайдено |
3002 | Транзакцію не знайдено |
Apple Pay
Віджет CryptoCash підтримує native-сценарій Apple Pay: платіжна панель iOS відкривається прямо у віджеті без редиректу на зовнішню сторінку.
Детальний опис умов доступності native-режиму, fallback-поведінки та обробки помилок див. у розділі Apple Native Pay.
Діаграми
Загальний сценарій оплати
