Fiat Module

Примечание: все числовые значения, суммы, курсы и идентификаторы в примерах являются иллюстративными и приведены только для демонстрации. Реальные значения зависят от рыночных условий, конфигурации аккаунта и параметров конкретной транзакции.

Обзор

Fiat Module — это подсистема платформы CryptoCash, которая позволяет мерчанту принимать фиатные платежи от конечных пользователей и получать криптовалюту на свой кошелёк. Интеграция выполняется через подписанные API-запросы. Платежи проводятся через платёжного провайдера (Mercuryo). Конечный пользователь завершает оплату в виджете CryptoCash, где выбирает способ оплаты. После обработки платежа мерчант получает webhook с финальным статусом. Поддерживаемые возможности:

Оплата картой, Apple Pay, Google Pay, SEPA и другие способы оплаты
Подписанные запросы (ED25519 или LEGACY/SHA256) для аутентификации мерчанта
Webhook-и мерчанту при каждом изменении статуса транзакции
Автоматический расчёт заработка мерчанта на основе partner_fee

Высокоуровневый сценарий

Мерчант отправляет подписанный API-запрос → получает URL для оплаты
Пользователь открывает URL → видит виджет CryptoCash
Пользователь выбирает способ оплаты
Платёжный провайдер обрабатывает платёж
Мерчант получает webhook при каждой смене статуса
После успешной оплаты автоматически рассчитывается заработок мерчанта

Два пути оплаты в виджете:

Способ оплаты	Сценарий
Apple Pay (native)	Пользователь оплачивает прямо в виджете — без редиректа на внешнюю страницу
Карта / другие способы	Пользователь редиректится на страницу платёжного провайдера для завершения оплаты

Подробное описание native-сценария Apple Pay см. в разделе Apple Native Pay.

Настройка мерчанта и 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 (рекомендуется)

payload    → JSON.stringify(payload)
json       → Buffer.from(json, 'utf8').toString('base64')  → data
sign       → Ed25519.sign(Buffer.from(data), privateKeyBytes) → signatureBytes
signature  → signatureBytes.toString('base64')

LEGACY (SHA256)

payload    → JSON.stringify(payload)
json       → Buffer.from(json, 'utf8').toString('base64')  → data
hash       → SHA256(privateKey + data) → hashHex
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"
}

Создание платежа — `form/retrieve`

Endpoint

POST https://rates.crypto-cash.world/merchant/api/v1/pay-fiat/form/retrieve

Подписанный запрос. Подпись и IP проверяются до обработки запроса.

Запрос

Поле 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	Прямая обработка платежа

Мерчант всегда получает URL виджета CryptoCash. URL страницы провайдера формируется внутри виджета после выбора способа оплаты и мерчанту не возвращается.

Публичное API мерчанта

Получение платежа

POST https://rates/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://rates.crypto-cash.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://rates.crypto-cash.world/merchant/api/v1/fiat-currencies/list
POST https://rates.crypto-cash.world/merchant/api/v1/pay-fiat/crypto-currencies/list

Оба endpoint-а используют подписанные запросы. Минимальный payload в data:

{ "publicKey": "..." }

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.

Обработка ошибок

Все ошибки API возвращаются в одном из двух форматов: Формат A — кодированная ошибка:

{ "code": 2020, "message": "..." }

Формат B — список ошибок (используется при ошибках декодирования):

{ "errors": [2010] }

Коды ошибок

Код	Описание
`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.

Fiat Module

Fiat Module

Обзор

Высокоуровневый сценарий

Настройка мерчанта и Fiat API Key

Что настраивает мерчант

Поля Fiat API Key

ED25519 vs LEGACY

Что проверяется при каждом запросе

Подписанные запросы

Структура запроса

ED25519 (рекомендуется)

LEGACY (SHA256)

Полный пример

Создание платежа — `form/retrieve`

Endpoint

Запрос

Ответ

Что происходит после запроса

Виджет CryptoCash и страница провайдера

Публичное API мерчанта

Получение платежа

Список платежей

Списки валют

Поля ответа платежа

Статусы транзакций

Обработка ошибок

Коды ошибок

Apple Pay

Диаграммы

Общий сценарий оплаты

​Fiat Module

​Обзор

​Высокоуровневый сценарий

​Настройка мерчанта и Fiat API Key

​Что настраивает мерчант

​Поля Fiat API Key

​ED25519 vs LEGACY

​Что проверяется при каждом запросе

​Подписанные запросы

​Структура запроса

​ED25519 (рекомендуется)

​LEGACY (SHA256)

​Полный пример

​Создание платежа — form/retrieve

​Endpoint

​Запрос

​Ответ

​Что происходит после запроса

​Виджет CryptoCash и страница провайдера

​Публичное API мерчанта

​Получение платежа

​Список платежей

​Списки валют

​Поля ответа платежа

​Статусы транзакций

​Обработка ошибок

​Коды ошибок

​Apple Pay

​Диаграммы

​Общий сценарий оплаты

Fiat Module

Обзор

Высокоуровневый сценарий

Настройка мерчанта и Fiat API Key

Что настраивает мерчант

Поля Fiat API Key

ED25519 vs LEGACY

Что проверяется при каждом запросе

Подписанные запросы

Структура запроса

ED25519 (рекомендуется)

LEGACY (SHA256)

Полный пример

Создание платежа — `form/retrieve`

Endpoint

Запрос

Ответ

Что происходит после запроса

Виджет CryptoCash и страница провайдера

Публичное API мерчанта

Получение платежа

Список платежей

Списки валют

Поля ответа платежа

Статусы транзакций

Обработка ошибок

Коды ошибок

Apple Pay

Диаграммы

Общий сценарий оплаты