Reference

Ошибки

Все наши HTTP-коды и значения error.code в одном месте, плюс справочник failure_code для отказа банка.

Все ошибки — JSON одного формата, с подходящим HTTP-статусом:

{
  "error": {
    "code":    "method_not_supported_by_bank",
    "message": "банк не поддерживает выбранный метод"
  }
}

Что вы можете встретить:

HTTP	code	когда
`400`	`bad_request`	невалидное тело или обязательное поле не заполнено
`401`	`unauthorized / invalid_token`	нет ключа, ключ просрочен или неверный
`401`	`signature_required`	на магазине включена обязательная подпись, заголовок X-Freefin-Signature не пришёл
`401`	`invalid_signature`	подпись X-Freefin-Signature не сходится с тем, что мы посчитали по телу
`403`	`live_not_enabled`	sk_live, но мерчант ещё не прошёл активацию
`403`	`ip_not_allowed`	IP вне allow-list магазина
`403`	`aml_blocked`	платёж отклонил наш AML-скоринг
`403`	`forbidden_purpose`	description или order_id содержит запрещённый контент; аккаунт уходит на проверку
`404`	`not_found`	объект не найден или принадлежит другому мерчанту
`409`	`not_pending`	платёж уже не в pending (для cancel)
`409`	`not_refundable`	возврат возможен только на платёж в succeeded
`409`	`fully_refunded`	платёж уже возвращён полностью
`422`	`amount_too_large`	сумма возврата больше доступного остатка
`422`	`route_not_configured`	для пары (shop, method) не настроен ни один коннектор
`422`	`method_not_supported_by_bank`	банк-эквайер не умеет выбранный метод
`429`	`rate_limited`	превышен лимит мерчанта на public-API; см. Retry-After
`500`	`db_error / internal`	внутренняя ошибка
`502`	`router_error`	ошибка вызова банка

Коды отказов

В ответе POST /payments и в webhook'е payment.failed приходит поле failure_code. Это наш унифицированный код, не сырой ответ банка. С банком взаимодействуем только мы. Сырой банковский код храним внутри для аудита, наружу не отдаём.

failure_code	когда
`insufficient_funds`	`на счёте плательщика недостаточно средств`
`card_declined`	`карта отклонена банком (общий кейс без уточнения)`
`card_expired`	`срок действия карты истёк`
`do_not_honor`	`банк не подтвердил операцию (CVV-фейл, 3DS-фейл и т.п.)`
`fraud_blocked`	`заблокировано anti-fraud (нашим или банка)`
`limit_exceeded`	`превышен лимит карты, мерчанта или нашего sandbox`
`aml_blocked`	`отклонено нашим AML-скорингом`
`customer_cancelled`	`покупатель сам отменил оплату на банковской странице`
`timeout`	`банк не вернул финальный статус за TTL банковской сессии`
`bank_unavailable`	`банк недоступен или ответил 5xx; повторите позже`
`bank_unknown`	`банк прислал нестандартный код; смотрите failure_message`

Поле failure_message — человеко-читаемое описание для UI. Подходит для прямого показа покупателю на странице ошибки.