Создание выплаты

Реквизит получателя — в теле запроса. USDT замораживается на шлюзе, заявка в пул исполнителей. Финальный статус — webhook.

POST https://api.protopays.io/api/v1/payins

Параметры тела (JSON)

Та же HMAC-схема, что у платежей — см. аутентификация. На ключе и методе шлюзы должны быть включены выплаты (payin).

Поле	Тип	Обяз.	Описание
orderId	string	да	Ваш id выплаты. Повтор с тем же orderId и методом — тот же объект (идемпотентность).
amount	number \| string	да	Сумма в RUB, минимум 1.
currency	string	да	Пример: RUB.
callbackUri	string (URL)	да	HTTPS URL для POST webhook о терминальном статусе.
method	string	да	Метод: sbp \| c2c (алиасы card, sim → нормализуются на сервере).
address	string	да	Реквизит получателя: телефон СБП, номер карты или счёт (вместо beneficiary.value).
recipient	string	да	ФИО или имя получателя (вместо beneficiary.holder).
code	string	нет	Код банка / идентификатор (например sber), попадает в beneficiary.bank.
bankName	string	нет	Человекочитаемое имя банка.
userId	string	нет	Id пользователя у мерчанта (аудит / metadata).
userIp	string	нет	IPv4/IPv6 плательщика у мерчанта.

Заголовки

Как для создания платежа: Content-Type: application/json, X-Merchant-Key-Id, Signature (и при необходимости X-Merchant-Secret).

Пример curl

curl -X POST 'https://api.protopays.io/api/v1/payins' \
  -H 'Content-Type: application/json' \
  -H 'X-Merchant-Key-Id: <KEY_ID>' \
  -H 'Signature: <SIGNATURE>' \
  -d '{
    "orderId": "payout-order-001",
    "amount": 500,
    "currency": "RUB",
    "method": "sbp",
    "address": "79001234567",
    "recipient": "IVAN IVANOV",
    "code": "sber",
    "callbackUri": "https://example.com/hooks/protopays-payin",
    "userId": "4095",
    "userIp": "188.11.55.10"
  }'

Ответ

Успех: Payin created. В beneficiary — маска; полный реквизит у исполнителя после взятия заявки. Статус: waiting.

{
  "message": "Payin created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "payout-order-001",
    "status": "waiting",
    "amount": "500.00",
    "currency": "RUB",
    "method": "sbp",
    "beneficiary": {
      "value": "7900******67",
      "holder": "IVAN IVANOV",
      "bank": "sber"
    },
    "frozenUsdt": "6.73",
    "expiresAt": "2026-05-22T14:00:00+00:00"
  }
}

Ошибки: недостаток USDT на шлюзе — insufficient_cashbox_balance; выплаты отключены — payin_api_disabled_for_credential. См. ошибки и статусы.