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

Укажите реквизиты получателя — создаётся заявка на выплату. Итог приходит в webhook.

POSThttps://api.protopays.io/api/v1/payins

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

На ключе должны быть включены выплаты. Подпись как у платежей — аутентификация.

Поле	Тип	Обяз.	Описание
orderId	string	да	Ваш id выплаты. Повтор с тем же orderId и методом — тот же объект (идемпотентность).
amount	number \| string	да	Сумма в RUB, минимум 1.
currency	string	да	Пример: RUB.
callbackUri	string (URL)	да	HTTPS URL для POST webhook о терминальном статусе.
method	string	да	Метод: sbp или c2c (card).
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

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"
  }'

Ответ

В beneficiary — маска реквизита. Статус обычно waiting.

json

{
  "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. Выплаты выключены — merchant_external_payins_disabled. См. ошибки.