Оплата банковской картой

Как проходит платёж

1. Ваш сервер создаёт платёжОтправьте подписанный запрос с уникальным Idempotency-Key.
2. NUMUS возвращает ссылкуОтвет содержит идентификатор платежа и paymentUrl.
3. Вы перенаправляете покупателяИспользуйте paymentUrl из ответа. Не встраивайте собственную форму ввода карты.
4. NUMUS проверяет результатВозврат браузера на returnUrl не считается подтверждением оплаты.
5. Вы получаете результатNUMUS отправляет payment.completed при успехе или payment.failed при окончательном отказе.

Создать карточный платёж

Запрос подписывается Ed25519. Добавьте уникальный Idempotency-Key длиной 16–128 символов. При сетевом повторе отправляйте то же тело и тот же ключ.

POST /api/card HTTP/1.1
Host: api.numus.online
Authorization: {"partnerID":"partner-001","key":"ssh-ed25519 ...","sign":"...","timestamp":"1784912400","nonce":"..."}
Idempotency-Key: card-order-2026-00042
Content-Type: application/json

{
  "orderID": "order-2026-00042",
  "amount": 1250.50,
  "currency": "RUB",
  "description": "Заказ №42",
  "customerID": "customer-381",
  "returnUrl": "https://merchant.example/orders/42/payment-result",
  "savePaymentMethod": false
}

Поля запроса

Успешный ответ — 201 Created:

{
  "id": "0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a21",
  "orderID": "order-2026-00042",
  "amount": 1250.5,
  "currency": "RUB",
  "status": "SUBMITTED",
  "paymentUrl": "https://secure-payment.example/...",
  "expiresAt": "2026-07-24T18:25:00Z",
  "statusUrl": "/api/card/0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a21"
}

Сохранить карту для подписки

Привязка создаётся только через первичный платёж на защищённой форме. NUMUS не принимает реквизиты карты в API. Передайте savePaymentMethod: true и период будущих списаний:

{
  "orderID": "initial-subscription-381",
  "amount": 100.00,
  "currency": "RUB",
  "description": "Подтверждение способа оплаты",
  "customerID": "customer-381",
  "savePaymentMethod": true,
  "recurringConsent": {
    "period": "P1M"
  }
}

Период списаний

Для PT1M отсчитываются 60 секунд, для PT1H — 60 минут от последнего успешного списания. Не путайте PT1M (минута) и P1M (календарный месяц). Календарные периоды рассчитываются в UTC с сохранением времени суток. Если в следующем месяце нет исходного числа, используется последний день этого месяца.

Согласие на вашей странице

После отдельного включения NUMUS вы можете показать согласие в своём интерфейсе и сразу отправить покупателя на защищённый ввод карты — без промежуточной страницы NUMUS. Добавьте capture: MERCHANT и передайте доказательство согласия:

"recurringConsent": {
  "capture": "MERCHANT",
  "reference": "consent-381-2026-08-01",
  "version": "numus-recurring-consent-ru-v1",
  "acceptedAt": "2026-08-01T12:00:00Z",
  "period": "P1M",
  "evidenceHash": "SHA-256 точного текста согласия"
}

evidenceHash — SHA-256 в lowercase hex от точного UTF-8 текста и условий, показанных покупателю. Сохраните этот текст, время и собственное доказательство действия покупателя. Галочка не должна быть отмечена заранее. Если capture не передан, продолжает работать стандартная страница NUMUS.

Не ждите состояния SUBMITTED перед перенаправлением. Для новой привязки первый ответ обычно содержит status: CREATED вместе с paymentUrl. Если ответ потерян, повторите тот же запрос с прежним Idempotency-Key или запросите statusUrl: пока согласие не подтверждено, оба способа возвращают ту же подписанную ссылку NUMUS.

Покупатель завершает первичный платёж по paymentUrl. После подтверждения в ответе статуса появляется NUMUS bindingId. Этот идентификатор можно хранить; внутренний токен карты клиенту не передаётся.

В согласии указывается только период, без суммы будущих списаний. Первичная успешная оплата считается первым списанием. Период действует на bindingId целиком. Привязка — сохранённый способ оплаты конкретного покупателя и его согласие. Одну привязку можно использовать для нескольких подписок, но все они делят один общий интервал. Разные проекты, номера заказов и ключи идемпотентности не позволяют списать несколько раз за период. Чтобы изменить период, отзовите привязку и создайте новую с новым согласием покупателя.

Выполнить повторное списание

POST /v1/recurring-payments HTTP/1.1
Host: api.numus.online
Authorization: {подписанный JSON}
Idempotency-Key: subscription-381-2026-08
Content-Type: application/json

{
  "merchantOrderId": "subscription-381-2026-08",
  "amount": "399.00",
  "currency": "RUB",
  "bindingId": "0190c5d1-0f08-7fc1-b3e8-a8c4ce278977",
  "description": "Подписка за август 2026"
}

Сумма передаётся строкой с двумя знаками после точки. Новый платёж получает новый merchantOrderId и Idempotency-Key. Сетевой повтор использует прежние значения и неизменное тело.

NUMUS принимает команду только после nextChargeAt. Пока предыдущее списание имеет статус CREATED, SUBMITTED или PENDING, новая команда по той же привязке также блокируется.

Если срок действия сохранённой карты закончился, NUMUS не отправляет команду списания в платёжный канал и переводит привязку в EXPIRED. Покупателю потребуется выполнить новый первичный платёж и сохранить действующую карту. Старый bindingId повторно не используется.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "recurring period has not elapsed",
  "nextChargeAt": "2026-08-25T15:00:00Z"
}

{
  "paymentId": "0190c5d4-25a4-770d-8464-d1a4fb437139",
  "merchantOrderId": "subscription-381-2026-08",
  "status": "SUBMITTED",
  "amount": "399.00",
  "currency": "RUB",
  "paymentMethod": "CARD_BINDING",
  "experience": "OFF_SESSION",
  "bindingId": "0190c5d1-0f08-7fc1-b3e8-a8c4ce278977",
  "createdAt": "2026-08-01T09:00:00Z",
  "statusUrl": "/api/card/0190c5d4-25a4-770d-8464-d1a4fb437139"
}

Получить или отозвать привязку

Список содержит NUMUS bindingId, период, lastChargedAt, nextChargeAt, статус и маску карты. Маска и срок могут отсутствовать, если платёжный канал их не подтвердил. Данные другого партнёра не возвращаются.

Статус EXPIRED означает, что срок действия сохранённой карты завершился. Для дальнейших повторных списаний создайте новую привязку через первичный платёж; менять формат API-запросов не нужно.

{
  "bindingId": "0190c5d1-0f08-7fc1-b3e8-a8c4ce278977",
  "customerId": "customer-381",
  "status": "ACTIVE",
  "consentId": "0190c5d0-6444-7e51-9419-c1ce2f5e1760",
  "period": "P1M",
  "lastChargedAt": "2026-07-25T15:00:00Z",
  "nextChargeAt": "2026-08-25T15:00:00Z",
  "createdAt": "2026-07-25T15:00:00Z"
}

За один запрос возвращается до 100 записей. Если nextPageToken не равен null, передайте его неизменным в параметре pageToken следующего запроса. Токен подписан NUMUS и действует только для того же клиента, покупателя и фильтра статуса.

Добавьте новый Idempotency-Key. После ответа 202 статус становится REVOKED, и NUMUS больше не принимает списания по этой привязке.

Проверить статус

Метод также подписывается Ed25519. Для GET тело пустое, поэтому в канонической строке используется SHA-256 пустого тела. Основной сигнал об успешной оплате — callback; GET нужен для восстановления состояния.

Что не должно попадать в NUMUS

• полный номер карты или PAN;
• CVV/CVC и срок действия;
• данные 3-D Secure;
• логины, пароли и другие платёжные секреты.

Покупатель вводит карточные данные только на странице из paymentUrl. Ваш backend и NUMUS API их не принимают.

Ошибки карточного метода