СБП (RUB)
Как создавать выплаты по номеру СБП
Выплаты позволяют отправлять средства с вашего мерчант-счёта на номера телефонов по СБП.
Создание выплаты по СБП состоит из двух шагов:
- Получите список банков, доступных для номера телефона получателя.
- Создайте выплату, передав
idвыбранного банка в полеaccount.bankName.
Перед тем как начать
Как авторизовывать запросы
Перед запросами убедитесь, что на вашем мерчант-счёте достаточно средств для выплаты.
В зависимости от метода формат номера телефона может отличаться. Некоторые
методы требуют указывать номер без префикса +7 или 7 (например,
9117883630 вместо 79117883630). Уточняйте формат, который ожидает
используемый метод.
Шаг 1. Получение списка банков
Перед созданием выплаты запросите список банков, которые могут принять перевод по СБП для номера телефона получателя:
GET /v1/payouts/banks?account=79117883630Пример запроса
curl -X GET "https://api.1capital.capital/v1/payouts/banks?account=79117883630" \
-H "X-Api-Token: YOUR_API_TOKEN"Параметры запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| account | string | ✅ Да | Номер телефона получателя |
Пример ответа
[
{ "id": "100000000004", "name": "T-Bank - Т-Банк" },
{ "id": "100000000111", "name": "Sberbank - Сбербанк" }
]Выберите банк, в котором получатель хочет получить средства, и используйте его
id в качестве значения account.bankName на следующем шаге.
Шаг 2. Создание выплаты
Отправьте POST-запрос для создания новой выплаты:
POST /v1/payoutsПример запроса
curl -X POST "https://api.1capital.capital/v1/payouts" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 1000,
"currency": "RUB",
"paymentType": "SBP",
"account": {
"name": "John Doe",
"requisites": "79117883630",
"bankName": "100000000004",
"userId": "user_12345"
},
"note": "Выплата по заказу №1234"
}'Параметры запроса
Основные параметры
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| amount | number | ✅ Да | Сумма выплаты |
| currency | string | ✅ Да | Код валюты |
| paymentType | string | ✅ Да | Тип платежа |
| account | object | ✅ Да | Реквизиты получателя |
| note | string | ❌ Нет | Заметка к выплате |
| externalId | string | ❌ Нет | Идентификатор выплаты в вашей системе |
| callbackUrl | string | ❌ Нет | Адрес webhook-уведомлений по выплате |
Объект account
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| name | string | ✅ Да | Имя получателя |
| requisites | string | ✅ Да | Реквизиты счёта (номер телефона) |
| bankName | string | ✅ Да | id банка из GET /v1/payouts/banks (например, 100000000004) |
| userId | string | ✅ Да | ID пользователя в вашей системе |
Поддерживаемые валюты
| Значение | Описание |
|---|---|
| RUB | Российский Рубль |
Типы платежей
| Значение | Описание |
|---|---|
| SBP | Перевод по СБП |
Пример успешного ответа
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"merchantId": "123e4567-e89b-12d3-a456-426614174000",
"amount": "1000",
"account": {
"name": "John Doe",
"requisites": "79117883630",
"bankName": "100000000004",
"userId": "user_12345"
},
"status": "CREATED",
"type": "SBP",
"requisites": {},
"statusMessage": null,
"metadata": null,
"callbackUrl": null,
"createdAt": "2023-03-21T12:34:56Z",
"updatedAt": "2023-03-21T12:34:56Z",
"completedAt": null
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
| id | string | UUID выплаты |
| merchantId | string | UUID вашего мерчанта |
| amount | string | Сумма выплаты |
| account | object | Реквизиты получателя |
| status | string | Текущий статус выплаты |
| type | string | Тип платежа |
| requisites | object | Дополнительные реквизиты |
| statusMessage | string / null | Сообщение статуса (если есть) |
| metadata | object / null | Дополнительные метаданные |
| callbackUrl | string / null | Адрес webhook-уведомлений для этой выплаты (null — настройки мерчанта) |
| createdAt | string | Время создания |
| updatedAt | string | Время последнего обновления |
| completedAt | string / null | Время завершения |
Статусы выплат
| Статус | Описание |
|---|---|
| CREATED | Выплата создана |
| PENDING | Выплата обрабатывается |
| COMPLETED | Выплата успешно завершена |
| FAILED | Ошибка выплаты |
| CANCELED | Выплата отменена |
| EXPIRED | Срок действия выплаты истёк |
Проверка статуса выплаты
Чтобы узнать текущий статус выплаты, отправьте GET-запрос:
GET /v1/payouts/{payoutId}Пример запроса
curl -X GET "https://api.1capital.capital/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "X-Api-Token: YOUR_API_TOKEN"Уведомления об изменении статуса выплаты также доставляются через
webhook'и: передайте callbackUrl в теле запроса или укажите его в
настройках мерчанта. Опрос статуса по ID может использоваться как резервный
способ (например, каждые 30 минут).
Webhook'и по выплатам
Рекомендации
- Всегда проверяйте баланс мерчанта перед созданием выплат
- Сначала получайте список банков и передавайте
idвыбранного банка вaccount.bankName - Учитывайте формат номера телефона, который требует метод (некоторые требуют номер без
+7/7) - Сохраняйте
idвыплаты из ответа для отслеживания статуса - Используйте webhook-уведомления (
callbackUrl) и проверяйте подписьX-Signature; опрос статуса по ID — резервный способ - Обрабатывайте все возможные значения статусов в своей интеграции