CloudPayments API: POST /payments/cards/charge — Оплата по криптограмме (одностадийная)

Оплата по криптограмме платёжных данных, сформированной скриптом Checkout. Для двухстадийной схемы тот же набор параметров отправляется на /payments/cards/auth. Если нужна 3-D Secure аутентификация, в ответе будет Success: false и в Model — AcsUrl, PaReq, TransactionId.

Пример ответа (некорректный запрос):

Пример ответа (требуется 3-D Secure):

Пример ответа (транзакция принята, сокращён):

Параметр	Где	Тип	Обяз.	Описание
`Amount`	body	Number	да	Сумма платежа, разделитель точка, не больше 2 знаков после точки; не меньше 0.01
`Currency`	body	String	нет	Валюта: RUB/USD/EUR/GBP, по умолчанию RUB
`IpAddress`	body	String	да	IP-адрес плательщика
`CardCryptogramPacket`	body	String	да	Криптограмма платёжных данных
`Name`	body	String	нет	Имя держателя карты латиницей
`PaymentUrl`	body	String	нет	Адрес сайта, с которого вызывается скрипт checkout
`InvoiceId`	body	String	нет	Номер счёта или заказа
`Description`	body	String	нет	Описание оплаты в свободной форме
`CultureName`	body	String	нет	Язык уведомлений: ru-RU, en-US
`AccountId`	body	String	нет	Идентификатор пользователя; нужен для создания подписки и получения токена
`Email`	body	String	нет	E-mail для квитанции об оплате
`Payer`	body	Object	нет	Данные плательщика: FirstName, LastName, MiddleName, Birth, Street, Address, City, Country, Phone, Postcode
`JsonData`	body	Json	нет	Произвольные данные транзакции; инструкции для подписки или онлайн-чека оборачиваются в объект cloudpayments
`SaveCard`	body	bool	нет	Вернуть карточный токен после успешной оплаты (работает при включённой настройке «Сохранение токена карты» в ЛК)
`X-Request-ID`	header	String	нет	Уникальный ключ для идемпотентности

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

{
    "Amount":10,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "IpAddress": "123.123.123.123",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "Name":"CARDHOLDER NAME",
    "CardCryptogramPacket":"01492500008719030128SM...",
    "Payer":
      {
        "FirstName":"Тест",
        "LastName":"Тестов",
        "Phone":"+71234567890"
    }
}

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

{"Success":false,"Message":"Amount is required"}

Базовые 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