Обзор
Начало работы
Merchant API делится на три поверхности:
- Payin Classic — двухэтапное пополнение счёта мерчанта прямым HTTP (
prepare_topup→confirm_topup). Без SDK. - Payin H2H — host-to-host приём платежей (карты, СБП). HTTP-контракт + готовые SDK на четыре языка.
- Payout — выплаты. Тот же набор SDK на четыре языка.
Для Payin и Payout используются разные ключи — это разные схемы подписи:
| Поверхность | Алгоритм | Что передаётся в заголовках |
|---|---|---|
| Payin Classic | ed25519 (Base64) | Key-Id, Signature |
| Payin H2H | ed25519 (Base64) | X-KeyId, X-Signature |
| Payout | RSA (PEM) | username + подпись по телу |
Сгенерируйте пару ключей
Приватный ключ остаётся у вас, публичный вы передаёте нам.
Получите идентификатор
- Для Payin мы вручную выдаём два значения
Key-Id— одно для подписи ваших запросов, другое для проверки наших ответов. - Для Payout мы вручную выдаём
username.
Без них API недоступен.
Выберите интеграцию
- Двухэтапное пополнение без SDK — Payin Classic.
- Принимаете карты/СБП с webhooks — Payin H2H (HTTP-контракт + SDK).
- Отправляете выплаты — Payout.
Обрабатывайте ошибки
Для Payin следите за полем ErrorInfo.Code, а не Message. Для Payout ориентируйтесь на тройку code / state / final. Списки — в Коды ошибок Payin и Коды ошибок Payout.
Контракт запросов
Все HTTP-запросы — POST, тело в JSON. HTTP-код ответа зависит от исхода: 200 при успехе, 400 / 403 при ошибках, 429 при превышении лимита запросов. Решение принимайте по полю SuccessCall (и ErrorInfo), а не только по HTTP-статусу. Формат даты: 2006-01-02T15:04:05+03:00.
Конверт запроса:
{
"Datetime": "2009-11-10T23:01:02+03:00",
"Payload": { /* зависит от endpoint */ }
}
Конверт успешного ответа:
{
"SuccessCall": true,
"Datetime": "2009-11-10T23:01:02+03:00",
"Payload": { /* зависит от endpoint */ }
}
Конверт ответа с ошибкой:
{
"SuccessCall": false,
"Datetime": "2009-11-10T23:01:02+03:00",
"ErrorInfo": { "Code": "invalidData", "Message": "..." }
}
HTTP-заголовки
Каждый запрос и каждый ответ несут два заголовка:
| Заголовок | Что внутри |
|---|---|
Key-Id | Идентификатор ключа (разный для запроса и ответа). В Payin H2H заголовок называется X-KeyId. |
Signature | ed25519-подпись тела в Base64. В Payin H2H заголовок называется X-Signature. |
openssl для генерации ключей ed25519 — он добавляет служебные байты. Используйте нативные библиотеки (sodium, crypto/ed25519, cryptography, crypto).Сетевые ограничения, тайминги, тестовая среда
Общие политики (белый список IP, rate limit, часовой пояс, расписание, тестовый каскад, лимиты сумм) собраны на отдельной странице — Общие вопросы (FAQ).