Обзор рекуррентных платежей

Рекуррентные платежи позволяют повторно списывать деньги без участия плательщика: подписки, автопополнения, рассрочки. Плательщик один раз подтверждает связку — источник оплаты, сохранённый у платёжного провайдера. Дальше вы создаёте списания по ID связки; платёжную страницу плательщик не открывает.

Перед тем как начать

Как это работает

Связка с первым платежом

Обычный запрос на создание заказа с объектом recurring. Всё остальное — поля customer, ссылка на оплату, H2H QR-ссылка, вебхуки — как у способа оплаты.

POST /v1/orders

curl -X POST "https://api.1capital.capital/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "amount": "990",
    "currency": "RUB",
    "serviceId": 12,
    "purpose": "Подписка, октябрь",
    "externalId": "order_1234",
    "externalUserId": "user_987",
    "customer": { "phone": "+79991234567", "ip": "198.51.100.24" },
    "recurring": {
      "saveBinding": true,
      "purpose": "Ежемесячная подписка",
      "externalId": "sub-42"
    }
  }'

В ответе — объект заказа с ID связки в recurringBindingId. Заказ направляется только на те способы оплаты сервиса, которые поддерживают рекуррентные платежи.

Для СБП плательщик получает QR-ссылку подписки (https://sub.nspk.ru/...) вместо разовой: оплачивая её, он соглашается и на будущие списания. Когда заказ становится COMPLETED, связка становится ACTIVE. Если заказ завершился как FAILED, EXPIRED или CANCELED, связка становится FAILED.

Связка без платежа

Сохраняет источник оплаты, ничего не списывая, — например, для бесплатного пробного периода.

POST /v1/recurring/bindings

curl -X POST "https://api.1capital.capital/v1/recurring/bindings" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "externalUserId": "user_987",
    "serviceId": 12,
    "purpose": "Ежемесячная подписка",
    "externalId": "sub-43"
  }'

В ответе — объект связки с confirmationUrl: перенаправьте туда плательщика, чтобы он подтвердил связку в своём банке. Связка остаётся PENDING до подтверждения и становится FAILED, если её не подтвердили за 24 часа.

Списание по связке

POST /v1/orders

purpose, currency, callbackUrl и остальные параметры заказа работают как обычно.

curl -X POST "https://api.1capital.capital/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "amount": "990",
    "currency": "RUB",
    "purpose": "Подписка, ноябрь",
    "externalId": "order_1235",
    "recurring": { "bindingId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" }
  }'

Списание уходит провайдеру, пока обрабатывается запрос. В ответе — объект заказа:

• PENDING — списание принято, результат придёт вебхуком ORDER_UPDATE;
• COMPLETED — провайдер сразу подтвердил списание;
• FAILED — провайдер отказал, например из-за нехватки средств. Создайте новое списание позже.

У списания нет платёжной страницы: ссылка на оплату и H2H-ручки отвечают на него 400. Комиссии, лимиты, зачисление на баланс и вебхуки — как у любого заказа.

Ошибки

Объект связки

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "ACTIVE",
  "isTest": false,
  "merchantId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e",
  "externalId": "sub-42",
  "externalUserId": "user_987",
  "purpose": "Monthly subscription",
  "initialOrderId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c",
  "confirmationUrl": null,
  "bankName": "Sberbank",
  "bankLogoUrl": null,
  "callbackUrl": null,
  "createdAt": "2026-10-21T12:34:56.000Z",
  "updatedAt": "2026-10-21T12:36:10.512Z",
  "activatedAt": "2026-10-21T12:36:10.512Z",
  "closedAt": null
}

Статусы связки

Управление связками

Связки плательщика

curl -X POST "https://api.1capital.capital/v1/recurring/bindings/find" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "pagination": { "page": 1, "perPage": 20 },
    "filter": { "externalUserId": "user_987", "status": ["ACTIVE"] }
  }'

Фильтры: externalUserId, externalId, status (любой из), fromDate, toDate (время создания), q (ID связки, ваш ID, ID плательщика или ID первого заказа). Сортировка: sort: [{ "field": "createdAt", "order": "desc" }] по status, createdAt, updatedAt, activatedAt. Ответ — { "data": [объекты связок], "total": число }.

Удаление связки

curl -X DELETE "https://api.1capital.capital/v1/recurring/bindings/0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" \
  -H "X-Api-Token: YOUR_API_TOKEN"

Возвращает связку в статусе DELETED. Связка, уже DELETED или FAILED, отвечает 409; если провайдер не ответил — 503, связка не меняется.

Сверка с провайдером

Плательщик может приостановить или удалить подписку в банковском приложении. Связки PENDING сверяются в фоне; для ACTIVE вызовите sync-status, когда списание отклонено, чтобы узнать, действует ли связка. Ответ — { "providerState", "previousStatus", "binding" }.

Тестовый режим

На тестовом способе оплаты настоящий источник оплаты не сохраняется:

• связка с первым платежом становится ACTIVE, когда её тестовый заказ становится COMPLETED (сумма 1000), и FAILED, если заказ не оплачен;
• связка без платежа становится ACTIVE в течение минуты, confirmationUrl — null;
• списания — тестовые заказы, их статус зависит от суммы: 1000 — COMPLETED, 1001 — CANCELED, 1002 — FAILED, 1003 — COMPLETED, затем REFUND, любая другая сумма — EXPIRED через 5 минут;
• sync-status отвечает 400, удаление работает без провайдера.

Рекомендации

Следующие шаги