Recurring payments overview

Recurring payments let you charge a payer again without their participation: subscriptions, auto top-ups, installments. The payer confirms a binding once — a payment source saved at the payment provider. After that you create charges by the binding ID; the payer does not open a payment page.

Before you start

How it works

Save a binding with the first payment

A regular order creation request with the recurring object. Everything else — customer fields, payment link, H2H QR link, webhooks — is the same as for the payment method.

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": "Subscription, October",
    "externalId": "order_1234",
    "externalUserId": "user_987",
    "customer": { "phone": "+79991234567", "ip": "198.51.100.24" },
    "recurring": {
      "saveBinding": true,
      "purpose": "Monthly subscription",
      "externalId": "sub-42"
    }
  }'

The response is the order object with the binding ID in recurringBindingId. The order is routed only to the payment methods of the service that support recurring payments.

For SBP the payer gets a subscription QR link (https://sub.nspk.ru/...) instead of a one-time one: by paying it they also agree to future charges. When the order is COMPLETED, the binding becomes ACTIVE. If the order ends as FAILED, EXPIRED or CANCELED, the binding becomes FAILED.

Create a binding without a payment

Saves the payment source without charging the payer, for example for a free trial.

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": "Monthly subscription",
    "externalId": "sub-43"
  }'

The response is the binding object with confirmationUrl: redirect the payer there to confirm the binding in their bank. The binding stays PENDING until it is confirmed and becomes FAILED if it is not confirmed within 24 hours.

Charge a binding

POST /v1/orders

purpose, currency, callbackUrl and the other order parameters work as usual.

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": "Subscription, November",
    "externalId": "order_1235",
    "recurring": { "bindingId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" }
  }'

The charge goes to the provider while the request is processed. The response is the order object:

• PENDING — the charge is accepted, the result comes in an ORDER_UPDATE webhook;
• COMPLETED — the provider confirmed the charge at once;
• FAILED — the provider refused, for example for insufficient funds. Create a new charge later.

A charge has no payment page: the payment link and the H2H endpoints answer 400 for it. Fees, limits, the balance credit and the webhooks are the same as for any order.

Errors

Binding object

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

Binding statuses

Manage bindings

Find a payer's bindings

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

Filters: externalUserId, externalId, status (any of), fromDate, toDate (creation time), q (binding ID, your ID, payer ID or first order ID). Sorting: sort: [{ "field": "createdAt", "order": "desc" }] by status, createdAt, updatedAt, activatedAt. The response is { "data": [binding objects], "total": number }.

Delete a binding

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

Returns the binding with the DELETED status. A binding that is already DELETED or FAILED answers 409; if the provider does not answer — 503, the binding is unchanged.

Sync with the provider

The payer can suspend or delete the subscription in their banking app. PENDING bindings are synced in the background; for an ACTIVE one, call sync-status when a charge is refused to find out whether the binding is still valid. The response is { "providerState", "previousStatus", "binding" }.

Test mode

On a test payment method no real payment source is saved:

• a binding from the first payment becomes ACTIVE when its test order is COMPLETED (amount 1000) and FAILED when the order is not paid;
• a binding without a payment becomes ACTIVE within a minute, confirmationUrl is null;
• charges are test orders, their status follows the amount: 1000 — COMPLETED, 1001 — CANCELED, 1002 — FAILED, 1003 — COMPLETED, then REFUND, any other amount — EXPIRED in 5 minutes;
• sync-status answers 400, deletion works without the provider.

Recommendations

Next steps