CloudPayments API: POST /subscriptions/create — Создание подписки

Подписка на рекуррентные платежи по токену карты. В ответ возвращается идентификатор подписки.

Пример ответа (сокращён):

Параметр	Где	Тип	Обяз.	Описание
Token	body	String	да	Токен карты, выданный после первого платежа
AccountId	body	String	да	Идентификатор пользователя
Description	body	String	да	Назначение платежа
Email	body	String	нет	E-mail плательщика
Amount	body	Number	да	Сумма платежа
Currency	body	String	да	Валюта: RUB/USD/EUR/GBP
RequireConfirmation	body	Bool	да	true — платежи по двухстадийной схеме
StartDate	body	DateTime	да	Дата и время первого платежа в UTC, в будущем
Interval	body	String	да	Интервал: Day, Week, Month
Period	body	Int	да	Период; вместе с интервалом: 1 Month — раз в месяц, 2 Week — раз в две недели
MaxPeriods	body	Int	нет	Максимальное количество платежей
CustomerReceipt	body	json	нет	Состав онлайн-чека

Пример запроса:

{
   "token": "477BBA133C182267FE5F086924ABDC5DB71F77BFC27F01F2843F2CDC69D89F05",
   "accountId": "user_x",
   "description": "Ежемесячная подписка на сервис example.com",
   "email": "user@example.com",
   "amount": 399,
   "currency": "RUB",
   "requireConfirmation": false,
   "startDate": "2021-11-02T21:00:00",
   "interval": "Day",
   "period": 5
}

Пример ответа:

{
    "Model": {
        "Id": "sc_221da6421dc44dbd2cc3464f6f083",
        "AccountId": "user_x",
        "Amount": 399,
        "Currency": "RUB",
        "Interval": "Day",
        "Period": 5
    },
    "Success": true,
    "Message": null
}

Базовые URL

• Боевой: https://api.cloudpayments.ru

Авторизация

Тип: Basic Auth

HTTP Basic Auth: логин — Public ID, пароль — API Secret. Оба значения есть в личном кабинете. Без заголовка авторизации или с неверными данными API возвращает HTTP 401 Unauthorized. API Secret нужно хранить в защищённом месте.

Параметры передаются методом POST в теле запроса: application/x-www-form-urlencoded («ключ=значение») или application/json. Ответ всегда JSON и содержит как минимум Success и Message.

{ "Success": false, "Message": "Invalid Amount value" }

Нюансы

• Success в ответе показывает только успешность запроса, а не статус транзакции. Статус транзакции смотрят в поле Model.Status или в уведомлениях.
• Идемпотентность включается заголовком X-Request-ID с уникальным значением; результат хранится 1 час, новый запрос требует нового значения.
• Если в целочисленное поле передать дробное число, ошибки не будет: значение математически округлится.
• Токен работает только на том терминале (publicId), где был получен.
• Финальный статус оплаты по токену СБП приходит только в Pay- и Fail-уведомлениях, а не в ответе на запрос.
• Для ТСП с MCC 4814 обязателен телефон плательщика в Payer.Phone (только цифры, например +71234567890), иначе банки отклоняют операции.
• Pay, Fail, Recurrent, Cancel, Confirm, Refund-уведомления повторяются до 100 раз (интервалы 1, 2, 5, 10, 30 минут), если сервер магазина недоступен или ответил кодом, отличным от нуля; таймаут ответа — 30 секунд.
• Подлинность уведомлений проверяют по заголовкам X-Content-HMAC и Content-HMAC: HMAC-SHA256 от тела запроса (для GET — от строки параметров) в UTF-8, ключ — API Secret, результат в base64.
• Уведомления приходят с адресов 185.98.81.0/28, 87.251.91.160/27, 46.46.175.96/27, 46.46.168.160/27, 162.55.174.97/32, 91.216.178.243/32.
• Ответ на Check-уведомление: {"code":0} — принять платёж; коды 10, 11, 12, 13, 20 отклоняют его (неверный InvoiceId, AccountId, сумма, платёж не принят, просрочен).

Сценарии с этим методом

• Подписка и списания по сохранённой карте

---

Если этого недостаточно — официальная документация: https://developers.cloudpayments.ru/#api Вся интеграция одним документом: https://mcp-everything.ru/integrations/cloudpayments.md