Getting Started

Коды ошибок (Payout)

Значения code / state / final в ответах Payout API.

Коды ошибок · Payout

Относится к Payout (HTTP API и SDK). Для приёма платежей — см. Коды ошибок Payin.

Формат ответа

Успешный ответ Payout — XML:

<response>
  <result id="unique-tx-id" code="0" state="60" final="1" trans="gateway-tx-id">
    <attribute name="fee" value="100" />
  </result>
</response>

Ошибка транспорта/подписи — отдельный XML-элемент:

<error>signature verification failed</error>

Матрица состояний

Решения принимайте только по полному набору code + state + final:

`code`	`state`	`final`	Состояние	SDK-хелпер
`0`	`60`	`1`	Успех — выплата проведена	`isSuccessful()`
`20`	`80`	`1`	Отказ — выплата не выполнена	`isFailed()`
`15`	`-2`	`1`	Не найдена — см. раздел ниже	`isNotFound()`
`1`	`40`	`0`	В обработке — опрашивайте статус	`isProcessing()`

final=1 — состояние финальное. final=0 — нужно периодически вызывать getStatus(id) до перехода в финал.

Если в ответе пришла комбинация значений, которой нет в таблице выше (например, code=20, но state или final отличаются), — никак её не интерпретируйте. Считайте, что ответ от сервера не получен, и продолжайте опрашивать getStatus(id) до получения одного из четырёх сочетаний из таблицы. Опираться только на code нельзя.

Состояние «не найдена» (`code=15, state=-2, final=1`)

Это особый случай — однозначно интерпретировать как неуспех нельзя.

Помечать транзакцию как неуспешную можно только если одновременно выполнены оба условия:

Изначальный <payment> (или Payment(...)) завершился ошибкой, нештатным ответом или вообще без ответа.
С момента запроса <payment> прошло более 15 минут.

Если на <payment> был получен штатный ответ «в обработке» (code=1, state=40, final=0), а затем getStatus вернул «не найдена» — это нештатная ситуация. Не присваивайте транзакции финальный неуспешный статус. Повторите getStatus(id) через несколько минут — в большинстве случаев придёт штатный ответ. Если ситуация повторяется — обращайтесь в саппорт.

Политика повторов

code=1, state=40, final=0 (в обработке) — не создавайте новую выплату. Опрашивайте getStatus(id) с интервалом 5–30 секунд.
code=15, state=-2, final=1 (не найдена) — см. раздел выше. Если оба условия выполнены — повторная отправка <payment> с тем же id безопасна (идемпотентно).
code=20, state=80, final=1 (отказ) — повторы того же id бесполезны. Если нужно повторить выплату — отправляйте с новым id.
<error>…</error> в ответе (подпись/формат/HTTP) — повторять только после устранения причины (проверить username, ключ, формат тела).

Атрибут `error-description`

Опциональный атрибут в ответе:

<attribute name="error-description" value="..." />

Текст и наличие атрибута определяются сервером. Атрибут может отсутствовать, приходить с пустым value, а формулировки для одной и той же ситуации — меняться со временем. Не парсите значение и не принимайте на его основе бизнес-решения; используйте только для логирования и ручного разбора.

Идемпотентность

id — ваш уникальный идентификатор. Сервер сохраняет соответствие id ↔ выплата.
Повторный <payment> с тем же id не создаёт дубль — вернётся текущее состояние.
Защита от дублей действует в течение 24 часов с момента первой отправки. При повторной отправке с тем же id спустя сутки и более защита от дублирующихся платежей не гарантируется.
Для опроса статуса используйте <status>, а не повторный <payment>.

Коды ошибок · Payin

Значения ErrorInfo.Code в ответах Merchant API для Payin Classic и Payin H2H.

FAQ и политики

Сетевые ограничения, тайминги, рейт-лимиты, тестовая среда — что важно знать перед интеграцией.