#Общие поля запроса
Поля разделены на две группы:
- Универсальные — принимаются всеми 17 методами (PayIn + PayOut)
- Зависящие от метода — нужны только некоторым (
bank_id, country_code, operator_id, owner_name, card_number, phone_number, account_number)
#Универсальные поля
| Поле | Тип | Обяз. | Описание |
|---|
amount | string | ✅ | Сумма в currency |
currency | string | ✅ | См. список валют |
merchant_transaction_id | string | ✅ | UNIQUE на мерчанта |
client_id | string | — | Только для интеграций по use_counterparty |
webhook_url | string | — | Per-tx callback (перебивает дефолт из dashboard) |
#PayIn — суффикс-зависимые поля
| Метод | bank_id | country_code | operator_id |
|---|
card | — | — | — |
card-internal | ✅ обяз. | — | — |
card-cross | — | ✅ обяз. | — |
card-internal-cross | ✅ обяз. | ✅ обяз. | — |
sbp | — | — | — |
sbp-internal | ✅ обяз. | — | — |
sbp-cross | — | ✅ обяз. | — |
sbp-internal-cross | ✅ обяз. | ✅ обяз. | — |
qr | — | — | — |
qr-internal | ✅ обяз. | — | — |
qr-cross | — | ✅ обяз. | — |
qr-internal-cross | ✅ обяз. | ✅ обяз. | — |
qr-nspk | — | — | — |
qr-nspk-multi | — | — | — |
mobile | — | — | — |
mobile-internal | — | — | ✅ обяз. |
mobile-cross | — | ✅ обяз. | — |
mobile-internal-cross | — | ✅ обяз. | ✅ обяз. |
account | — | — | — |
acquiring | — | — | — |
«—» = поле не нужно (передадите — будет проигнорировано).
bank_id берётся из GET /merchant/banks, country_code — ISO-2, operator_id — UUID мобильного оператора.
#PayOut — обязательные доп. поля
| Поле | Тип | Обяз. | Описание |
|---|
owner_name | string | ✅ | ФИО получателя (для всех PayOut) |
bank_id | UUID | ✅ | UUID банка из GET /merchant/banks (для всех PayOut). Если банк не найден → 400 INVALID_BANK |
#PayOut — поля по методам
| Метод | Доп. обязательное поле | Формат |
|---|
card-out | card_number | 16 цифр, без пробелов и тире |
sbp-out | phone_number | 11 цифр без + |
account-out | account_number | 20 цифр |
#СВОДКА — какие поля валидируем
| Метод | Required-поля (помимо amount/currency/merchant_transaction_id) |
|---|
payin/card | — |
payin/card-internal | bank_id |
payin/card-cross | country_code |
payin/card-internal-cross | bank_id + country_code |
payin/sbp | — |
payin/sbp-internal | bank_id |
payin/sbp-cross | country_code |
payin/sbp-internal-cross | bank_id + country_code |
payin/qr | — |
payin/qr-internal | bank_id |
payin/qr-cross | country_code |
payin/qr-internal-cross | bank_id + country_code |
payin/qr-nspk | — |
payin/qr-nspk-multi | — |
payin/mobile | — |
payin/mobile-internal | operator_id |
payin/mobile-cross | country_code |
payin/mobile-internal-cross | operator_id + country_code |
payin/account | — |
payin/acquiring | return_url |
payout/card | card_number, owner_name, bank_id |
payout/sbp | phone_number, owner_name, bank_id |
payout/account | account_number, owner_name, bank_id |
Любые другие поля в запросе → 400 VALIDATION_ERROR.
Optional всегда: client_id, webhook_url.
#Что вернёт сервер при ошибке валидации
| HTTP | Code | Когда |
|---|
| 400 | VALIDATION_ERROR | Поле отсутствует или невалидно (или передано лишнее поле) |
| 400 | INVALID_BANK | bank_id корректный UUID, но банка нет в справочнике (PayOut) |
| 400 | DUPLICATE_ORDER | merchant_transaction_id уже использовался |
