API

Обзор

API принимает заявки на перевод и отдаёт их текущее состояние. Обработка асинхронная: заявка регистрируется сразу, а финальный исход (подтверждение или отказ) становится известен позже — его нужно запрашивать через статус операции.

• Все запросы к /transfers/** подписываются HMAC-SHA256 секретом терминала — см. Аутентификация.
• Актуальный курс конверсии для терминала — GET /api/v1/rates/{terminalId} (без подписи), см. Получение курса.
• Идемпотентность приёма — по полю externalId, см. создание заявки.
• Каждая операция привязана к терминалу (канал интеграции); терминал видит только свои операции.
• Статусы операций PENDING / COMPLETED / REJECTED — см. Статусы операции.

Соглашения

Аутентификация

Каждый запрос к /api/v1/transfers/** подписывается по схеме HMAC-SHA256 симметричным секретом терминала. При подключении банк получает пару: terminalId (UUID) и secret (сырой ключ). Секрет на стороне сервиса хранится зашифрованным; в открытом виде существует только у интегратора.

Канонизация запроса

Строка для подписи собирается из четырёх частей, разделённых символом \n (LF):

METHOD            // POST или GET
PATH              // /api/v1/transfers  (без host и query)
X-Timestamp       // тот же литерал, что уйдёт в заголовке
hex(SHA-256(body))// для GET тело пустое → хэш пустой строки

Шаги формирования подписи

1. Взять текущее время UTC, ISO-8601 c Z — это значение пойдёт и в X-Timestamp, и в канон-строку (один и тот же литерал).
2. Сериализовать тело ровно в те байты, что уйдут в сеть; после подсчёта хэша тело не переформатировать (пробелы, порядок ключей, экранирование должны остаться неизменными).
3. Посчитать bodyHash = hex(SHA-256(rawBody)), lowercase.
4. Собрать канон-строку (см. выше).
5. signature = hex(HMAC-SHA256(secret, canonical)), lowercase.
6. Отправить запрос с заголовками X-Terminal-Id, X-Timestamp, X-Signature.

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

Подпись собирается через openssl, затем запрос уходит через curl:

SECRET="<secret>"; TS="2026-06-22T19:02:12Z"
BODY='{"externalId":"...","terminalId":"...", ... }'

BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
CANON=$(printf 'POST\n/api/v1/transfers\n%s\n%s' "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl -X POST https://<host>/api/v1/transfers \
  -H 'Content-Type: application/json' \
  -H "X-Terminal-Id: <terminalId>" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  --data "$BODY"

Заголовки

Получение курса

Возвращает актуальный курс конверсии, персональный для терминала. Вызывайте его, чтобы получить значение поля rate перед созданием заявки: курс индивидуален для каждого партнёра и может меняться во времени. Курсовой профиль сопоставляется терминалу на нашей стороне — партнёру достаточно передать свой terminalId.

Подпись не требуется. Заголовки X-Terminal-Id / X-Timestamp / X-Signature для этого запроса не нужны — достаточно указать terminalId в пути.

Path-параметры

В пути /rates/{terminalId} подставляется {terminalId}:

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

curl https://api-test.coinpay.by/api/v1/rates/3b9aa1d4-7c2e-4d1a-9f3b-5e8c1a2d6f80

Ответ

{
  "currencyOne": "RUB",
  "currencyTwo": "BYN",
  "amountOne": "1",
  "amountTwo": "0.036352"
}

Читается как amountOne currencyOne = amountTwo currencyTwo: в примере 1 RUB = 0.036352 BYN. Значение amountTwo — это актуальный курс, который подставляется в поле rate запроса на создание заявки.

На текущем этапе курс отдаётся по паре RUB → BYN; query-параметры не поддерживаются.

Коды ответа

Создание заявки

Создаёт операцию: в ответе PENDING (далее асинхронная обработка) либо сразу REJECTED с reasonCode = TERMINAL_INACTIVE, если терминал отключён. Идемпотентно по externalId. Поле reasonCode присутствует только при status = REJECTED; при PENDING опускается.

Тело запроса

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

curl -X POST https://api-test.coinpay.by/api/v1/transfers \
  -H 'Content-Type: application/json' \
  -H "X-Terminal-Id: <terminalId>" \
  -H "X-Timestamp: <timestamp>" \
  -H "X-Signature: <signature>" \
  --data '{
  "externalId": "f42ac22b-58cc-4335-a237-0e03b3c3d473",
  "terminalId": "3b9aa1d4-7c2e-4d1a-9f3b-5e8c1a2d6f80",
  "source": { "currency": "RUB", "amount": "10000.00" },
  "target": { "currency": "BYN", "amount": "360.19" },
  "rate": "0.036352000000",
  "executionDeadline": "2026-06-23T00:30:00",
  "description": "Monthly support",
  "sender": {
    "firstName": "John", "lastName": "Doe", "middleName": "Nikolaevich",
    "birthDate": "1987-05-22",
    "fullAddress": "ul. Sadovaya 17, kv. 42, Voronezh, 394000, RU",
    "country": "RU", "state": "Voronezh Oblast", "city": "Voronezh",
    "street": "ul. Sadovaya 17, kv. 42", "zip": "394000"
  },
  "recipient": { "card": "9112874453219031", "holder": "Anastasia Kovaleva" }
}'

Ответ

Тело ответа одинаково для 201 и 200:

{
  "id": "9b1f8e22-0e0d-4b94-9a3d-3a2e5f1c7e10",
  "externalId": "f42ac22b-58cc-4335-a237-0e03b3c3d473",
  "status": "PENDING",
  "executionDeadline": "2026-06-23T00:30:00",
  "createdAt": "2026-06-22T19:02:12",
  "updatedAt": "2026-06-22T19:02:12"
}

Коды ответа

Статус операции

Возвращает текущее состояние операции. Действует изоляция по терминалу: операция видна только терминалу-владельцу. Запрос статуса чужой операции отвечает 404 (существование чужой операции не подтверждается). Поле reasonCode присутствует только при status = REJECTED (см. каталог); description — человекочитаемая детализация (например, текст отказа от PSP), может быть null.

Path-параметры

В пути /transfers/{id}/status подставляется {id}:

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

curl https://api-test.coinpay.by/api/v1/transfers/9b1f8e22-0e0d-4b94-9a3d-3a2e5f1c7e10/status \
  -H "X-Terminal-Id: <terminalId>" \
  -H "X-Timestamp: <timestamp>" \
  -H "X-Signature: <signature>"

Ответ

{
  "id": "9b1f8e22-0e0d-4b94-9a3d-3a2e5f1c7e10",
  "status": "REJECTED",
  "reasonCode": "PROVIDER_DECLINED",
  "description": "Card declined by issuer (51)",
  "executionDeadline": "2026-06-23T00:30:00",
  "updatedAt": "2026-06-22T19:05:00"
}

Коды ответа

Модель данных

Отправитель

Объект sender в теле запроса.

Получатель

Объект recipient в теле запроса.

Денежная величина

Объекты source (списание) и target (зачисление) в теле запроса.

Статусы операции

Наружу отдаётся публичная проекция состояния — внутренние этапы обработки не раскрываются. Поле status в ответах на создание заявки и статус операции принимает одно из трёх значений:

Причина отказа

Поле reasonCode. Присутствует только при status = REJECTED; для PENDING / COMPLETED опускается.

Ошибки

Все ошибки возвращаются единым форматом. Поле traceId совпадает с заголовком X-Trace-Id ответа — указывайте его при обращении в поддержку для быстрой локализации запроса в логах.

{
  "code": "UNAUTHORIZED",
  "message": "Terminal authentication failed",
  "traceId": "b2c1...e7f0"
}