Payin Classic

Prepare → Confirm

Двухэтапное создание операции пополнения.

Двухэтапное пополнение

Создание операции пополнения — двухэтапное:

`/prepare_topup`

Регистрирует операцию. Клиенту ещё не выставляется счёт — операция подготовлена.

`/confirm_topup`

Запускает операцию. Должен быть вызван сразу после /prepare_topup — иначе подготовленная операция отменится.

`/prepare_topup`

Запрос

{
  "Datetime": "2009-11-10T23:01:02+03:00",
  "Payload": {
    "Payer": "someUserName",
    "Currency": "RUB",
    "DesireSum": 1000.01,
    "WorkKind": "topupMerchantAccount",
    "paymentMethod": "sbp",
    "FailRedirectUrl": "https://example.com/fail",
    "SuccessRedirectUrl": "https://example.com/success",
    "payerBank": "100000000111"
  }
}

Поле	Обяз.	Описание
`Payer`	да	Уникальный идентификатор пользователя в системе мерчанта
`Currency`	да	`RUB`. Поддержка `USDT` — по согласованию; для `USDT` указывайте `walletAddress`.
`DesireSum`	да	Желаемая сумма пополнения (> 0)
`WorkKind`	да	Варианты ниже
`paymentMethod`	да	Метод оплаты: `card`, `sbp`, `tpay` или `any`. `any` — без привязки к методу (выбор на стороне виджета).
`payerBank`	опц.¹	Код банка плательщика (отправителя). ¹Может быть обязательным по условиям работ.
`FailRedirectUrl`, `SuccessRedirectUrl`	опц.	Куда редиректить пользователя по итогу платежа. Не полагайтесь на то, что пользователь их посетит.
`WebhookStatusUrl`	опц.	URL (`http`/`https`), на который POST-ом приходят смены статуса операции. См. Статус операции.
`email`	опц.	E-mail плательщика.
`userCreatedAt`	опц.	Дата регистрации пользователя в системе мерчанта (ISO 8601, напр. `2009-11-10T23:01:02+03:00`).
`walletAddress`	опц.	Адрес кошелька плательщика (для крипто-пополнений / `USDT`).

paymentMethodобязателен. Запрос без него отклоняется с ErrorInfo.Code = otherError (malformed request: payment method is empty).

Значения WorkKind:

topupMerchantAccount — базовый.
topupMerchantAccount_usingTelegram — согласовывается через менеджера.
topupMerchantAccount_usingWebsite — согласовывается через менеджера.

Пример с дополнительными опциональными полями:

{
  "Datetime": "2009-11-10T23:01:02+03:00",
  "Payload": {
    "Payer": "someUserName",
    "Currency": "RUB",
    "DesireSum": 1000.01,
    "WorkKind": "topupMerchantAccount",
    "paymentMethod": "card",
    "payerBank": "100000000111",
    "WebhookStatusUrl": "https://example.com/webhooks/topup-status",
    "email": "payer@example.com",
    "userCreatedAt": "2024-01-15T10:00:00+03:00"
  }
}

Ответ

{
  "SuccessCall": true,
  "Datetime": "2009-11-10T23:01:02+03:00",
  "Payload": {
    "RegisteredUid": "1234567"
  }
}

RegisteredUid — идентификатор операции (строка с числовым значением), нужен для /confirm_topup и /topup_status. Передавайте его обратно без изменений.

При ошибке запрос можно повторить через 5 секунд.

`/confirm_topup`

Вызов можно делать несколько раз — повторно операция не создаётся. Но вызвать хотя бы один раз после /prepare_topup обязательно, иначе операция будет отменена.

Запрос

{
  "Datetime": "2009-11-10T23:01:02+03:00",
  "Payload": {
    "RegisteredUid": "1234567"
  }
}

Ответ

{
  "SuccessCall": true,
  "Datetime": "2009-11-10T23:01:02+03:00",
  "Payload": {
    "RedirectUrl": "https://example.com/path/page"
  }
}

Пользователя нужно перенаправить на RedirectUrl методом GET.

Обработка ошибочного ответа

Ошибочный ответ не означает, что запрос фактически не выполнен (например, сервер мог получить запрос, но ответ потерялся из-за сетевого сбоя). Обязательно:

повторите запрос через несколько секунд, или
запросите статус через /topup_status.

/balance

/balance — баланс мерчанта по валютам.

/topup_status

/topup_status — lifecycle статусов операции.