CloudPayments API: Принять оплату картой на сайте

Сценарий из mcp-everything. Актуально на 2026-10-24.

Одностадийная оплата: данные карты шифрует скрипт CloudPayments на странице, сервер магазина проводит платёж по криптограмме.

  1. На странице оплаты подключи скрипт Checkout: он принимает данные карты и отдаёт криптограмму — сами данные карты на твой сервер не попадают.
  2. С сервера проведи платёж: POST /payments/cards/charge с Amount, Currency, IpAddress плательщика, CardCryptogramPacket, InvoiceId (номер заказа) и AccountId. Авторизация — Basic: Public ID и API Secret. Передай заголовок X-Request-ID, чтобы повтор запроса не создал второй платёж.
  3. Если банку нужна 3-D Secure, ответ придёт с Success: false и Model с AcsUrl, PaReq и TransactionId. Отправь покупателя POST-формой на AcsUrl с MD = TransactionId, PaReq и TermUrl — адресом возврата на твой сайт.
  4. Когда покупатель вернётся на TermUrl с MD и PaRes, заверши оплату: POST /payments/cards/post3ds с TransactionId и PaRes.
  5. Успех запроса (Success) — не то же самое, что успех оплаты: статус транзакции смотри в Model.Status, причину отказа — в коде ошибки (например, 5051 — недостаточно средств).
curl -X POST https://api.cloudpayments.ru/payments/cards/charge \
  -u '<Public ID>:<API Secret>' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: order-1042-try-1' \
  -d '{
        "Amount": 1500.00,
        "Currency": "RUB",
        "IpAddress": "203.0.113.7",
        "CardCryptogramPacket": "<криптограмма из Checkout>",
        "InvoiceId": "1042",
        "AccountId": "user_42",
        "Description": "Оплата заказа № 1042",
        "Email": "buyer@example.ru"
      }'

Базовые URL

Авторизация

Тип: 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" }

Методы сценария

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

POST /payments/cards/post3ds — Завершение оплаты после 3-D Secure

Плательщика отправляют POST-формой на AcsUrl с параметрами MD (= TransactionId), PaReq и TermUrl. После аутентификации он возвращается на TermUrl с MD и PaRes, после чего вызывается этот метод. В ответ приходит информация об успешной или отклонённой транзакции.

Параметр Где Тип Обяз. Описание
TransactionId body Long да Значение параметра MD
PaRes body String да Значение одноимённого параметра

Нюансы

Другие сценарии

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