CloudPayments API API

Отрасль: Платежи и финансы. Актуально на 2026-10-24.

Программный интерфейс платёжного сервиса CloudPayments для приёма карточных платежей. Через API проводят оплату по криптограмме карты и по сохранённому токену (рекуррентные платежи), подтверждают, отменяют и возвращают платежи, управляют подписками и выставляют счета со ссылкой на оплату. О результатах платежей сервис сообщает уведомлениями (вебхуками) на сайт магазина.

Сценарии

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

Одностадийная оплата: данные карты шифрует скрипт 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"
      }'

Двухстадийная оплата: заблокировать и списать позже

Деньги замораживаются при заказе и списываются после сборки — или возвращаются на карту, если товара нет.

  1. Проведи авторизацию вместо списания: POST /payments/cards/auth с теми же параметрами, что и одностадийная оплата. Деньги заблокируются на карте.
  2. Когда заказ собран, подтверди списание: POST /payments/confirm с TransactionId и Amount. Сумма может быть меньше заблокированной — например, если часть товара закончилась.
  3. Если заказ отменён, сними блокировку: POST /payments/void с TransactionId.
  4. Для оплат по сохранённой карте в двухстадийной схеме — /payments/tokens/auth, подтверждение тем же /payments/confirm.
# Подтвердить списание (сумма — не больше заблокированной)
curl -X POST https://api.cloudpayments.ru/payments/confirm \
  -u '<Public ID>:<API Secret>' \
  -H 'Content-Type: application/json' \
  -d '{"TransactionId": 455, "Amount": 65.98}'

# Или отменить блокировку
curl -X POST https://api.cloudpayments.ru/payments/void \
  -u '<Public ID>:<API Secret>' \
  -H 'Content-Type: application/json' \
  -d '{"TransactionId": 455}'

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

Ежемесячная оплата сервиса или списание без участия покупателя по карте, сохранённой при первой оплате.

  1. Первая оплата — обычная, по криптограмме, обязательно с AccountId (идентификатором пользователя у тебя). После успешной оплаты CloudPayments вернёт токен карты в данных транзакции и в Pay-уведомлении — сохрани его.
  2. Для регулярных списаний создай подписку: POST /subscriptions/create с Token, AccountId, Description, Amount, Currency, RequireConfirmation, StartDate (в UTC, в будущем), Interval (Day, Week, Month) и Period. Сохрани Id подписки из ответа.
  3. Для разовых списаний без подписки используй POST /payments/tokens/charge с Token, AccountId, Amount и TrInitiatorCode = 0 (списание инициирует магазин); для оплаты по расписанию — PaymentScheduled = 1.
  4. Отключить подписку: POST /subscriptions/cancel с Id.
  5. Токен работает только на том терминале (Public ID), где был получен.
curl -X POST https://api.cloudpayments.ru/subscriptions/create \
  -u '<Public ID>:<API Secret>' \
  -H 'Content-Type: application/json' \
  -d '{
        "Token": "<токен карты>",
        "AccountId": "user_42",
        "Description": "Подписка на сервис example.ru",
        "Email": "user@example.ru",
        "Amount": 399,
        "Currency": "RUB",
        "RequireConfirmation": false,
        "StartDate": "2026-11-01T09:00:00",
        "Interval": "Month",
        "Period": 1
      }'

Вернуть деньги покупателю

Полный или частичный возврат по заказу.

  1. Найди платёж по номеру заказа: POST /v2/payments/find с InvoiceId. Если по заказу было несколько операций, вернётся последняя — возьми TransactionId оплаты.
  2. Сделай возврат: POST /payments/refund с TransactionId и Amount — суммой возврата (можно меньше суммы оплаты). Если магазин отправляет чеки через CloudPayments, передай состав чека возврата в JsonData.
  3. В ответе — TransactionId операции возврата; сохрани его рядом с заказом.
  4. Возвраты по транзакциям старше года не проводятся.
curl -X POST https://api.cloudpayments.ru/v2/payments/find \
  -u '<Public ID>:<API Secret>' -H 'Content-Type: application/json' \
  -d '{"InvoiceId": "1042"}'

curl -X POST https://api.cloudpayments.ru/payments/refund \
  -u '<Public ID>:<API Secret>' -H 'Content-Type: application/json' \
  -d '{"TransactionId": 455, "Amount": 500}'

Выставить счёт ссылкой на оплату

Оплата без корзины на сайте: отправить клиенту ссылку в мессенджер, по почте или SMS.

  1. Создай счёт: POST /orders/create с Amount, Description, Email и InvoiceId. Чтобы CloudPayments сам отправил ссылку, добавь SendEmail = true (или Phone и SendSms).
  2. В ответе Model.Url — ссылка на страницу оплаты, её можно отправить клиенту самостоятельно.
  3. SuccessRedirectUrl и FailRedirectUrl вернут клиента на твой сайт после оплаты.
  4. Об оплате узнавай из Pay-уведомления: по InvoiceId найди счёт у себя.
curl -X POST https://api.cloudpayments.ru/orders/create \
  -u '<Public ID>:<API Secret>' \
  -H 'Content-Type: application/json' \
  -d '{
        "Amount": 4900.0,
        "Currency": "RUB",
        "Description": "Консультация 24 октября",
        "Email": "client@example.ru",
        "InvoiceId": "INV-305",
        "SendEmail": true,
        "SuccessRedirectUrl": "https://example.ru/paid"
      }'

Принимать уведомления об оплате и сверять платежи

Pay-, Fail- и Check-уведомления сообщают о результате оплаты; сверка за период ловит то, что могло потеряться.

  1. Укажи адреса уведомлений в личном кабинете. Проверяй подлинность каждого: HMAC-SHA256 от тела запроса с ключом API Secret, в base64, должен совпасть с заголовком Content-HMAC (или X-Content-HMAC).
  2. На Check-уведомление (до списания) отвечай {"code":0}, чтобы принять платёж, или кодом 10–13, 20, чтобы отклонить (неверный заказ, сумма и т. д.). На Pay и Fail тоже отвечай {"code":0}, иначе CloudPayments будет повторять уведомление до 100 раз.
  3. Сомневаешься в статусе — запроси транзакцию: POST /payments/get с TransactionId.
  4. Раз в день сверяй операции за период: POST /v2/payments/list с CreatedDateGte, CreatedDateLte и PageNumber — 100 записей на страницу.
import base64, hashlib, hmac

def is_valid(body: bytes, header_hmac: str, api_secret: str) -> bool:
    digest = hmac.new(api_secret.encode(), body, hashlib.sha256).digest()
    return hmac.compare_digest(base64.b64encode(digest).decode(), header_hmac)

# В обработчике: if not is_valid(request.body, request.headers["Content-HMAC"], API_SECRET): вернуть 403
# Затем обновить заказ по InvoiceId и ответить {"code": 0}

Базовые 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 /test — Тестовый метод

Проверка взаимодействия с API. Параметров нет, в ответ возвращается статус запроса.

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

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

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/auth — Оплата по криптограмме (двухстадийная)

Те же параметры и ответы, что у /payments/cards/charge. Деньги блокируются и списываются только после вызова /payments/confirm.

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

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

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

POST /payments/tokens/charge — Оплата по токену (рекарринг)

Оплата по токену, полученному при оплате по криптограмме или через Pay-уведомление. Для двухстадийной схемы — /payments/tokens/auth. Токен работает только на том терминале (publicId), где был получен.

Параметр Где Тип Обяз. Описание
Amount body Number да Сумма платежа, не больше 2 знаков после точки
Currency body String нет Валюта, по умолчанию RUB
AccountId body String да Идентификатор пользователя
TrInitiatorCode body Int да Инициатор списания: 0 — ТСП, 1 — держатель карты
PaymentScheduled body Int нет Оплата по расписанию: 0 — без расписания (по умолчанию), 1 — по расписанию
Token body String да Токен
InvoiceId body String нет Номер счёта или заказа
Description body String нет Назначение платежа
IpAddress body String нет IP-адрес плательщика
Email body String нет E-mail для квитанции
Payer body Object нет Данные плательщика
JsonData body Json нет Произвольные данные транзакции

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

{
    "Amount":59,
    "Currency":"RUB",
    "InvoiceId":"1234567",
    "Description":"Оплата товаров в example.com",
    "AccountId":"user_x",
    "TrInitiatorCode": 0,
    "PaymentScheduled": 1,
    "Token":"success_1111a3e0-2428-48fb-a530-12815d90d0e8"
}

POST /payments/tokens/auth — Оплата по токену (двухстадийная)

Те же параметры, что у /payments/tokens/charge; требует последующего подтверждения через /payments/confirm.

POST /payments/confirm — Подтверждение оплаты

Подтверждение платежа, проведённого по двухстадийной схеме.

Параметр Где Тип Обяз. Описание
TransactionId body Long да Номер транзакции в системе
Amount body Number да Сумма подтверждения в валюте транзакции
JsonData body Json нет Данные транзакции, в том числе для онлайн-чека

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

{"TransactionId":455,"Amount":65.98}

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

{"Success":true,"Message":null}

POST /payments/void — Отмена оплаты

Параметр Где Тип Обяз. Описание
TransactionId body Long да Номер транзакции в системе

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

{"TransactionId":455}

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

{"Success":true,"Message":null}

POST /payments/refund — Возврат денег

Возвраты по транзакциям старше года не проводятся.

Параметр Где Тип Обяз. Описание
TransactionId body Long да Номер транзакции оплаты
Amount body Number да Сумма возврата в валюте транзакции
JsonData body Json нет Данные транзакции, в том числе для онлайн-чека

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

{"TransactionId":455, "Amount": 100}

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

{
    "Model": {
        "TransactionId": 568
    },
    "Success": true,
    "Message": null
}

POST /payments/get — Просмотр транзакции

Детализация транзакции по номеру.

Параметр Где Тип Обяз. Описание
TransactionId body Long да Номер транзакции

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

{"TransactionId":897749645}

POST /v2/payments/find — Проверка статуса платежа

Поиск платежа по номеру заказа. Если найдено несколько платежей, возвращается последняя операция. Новый метод ищет по всем операциям, включая возвраты и выплаты на карту; старый адрес — /payments/find.

Параметр Где Тип Обяз. Описание
InvoiceId body String да Номер заказа

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

{"InvoiceId":"123456789"}

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

{"Success":false,"Message":"Not found"}

POST /payments/list — Список транзакций за день

Параметр Где Тип Обяз. Описание
Date body String да Дата создания операций
TimeZone body String нет Код временной зоны, по умолчанию UTC

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

{"Date":"2014-08-09", "TimeZone": "MSK"}

POST /v2/payments/list — Список транзакций за период

Результат сортируется по CreatedDate от старых к новым, 100 записей на страницу.

Параметр Где Тип Обяз. Описание
CreatedDateGte body Date да Начальная дата создания операций
CreatedDateLte body Date да Конечная дата создания операций
PageNumber body Number да Номер страницы, от 1
TimeZone body String нет Код временной зоны, по умолчанию UTC
Statuses body String Array нет Статусы: Authorized, Completed, Cancelled, Declined; по умолчанию все

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

{
    "PageNumber": 1,
    "CreatedDateGte":"2021-03-09T00:00:00+03:00",
    "CreatedDateLte":"2021-03-10T00:00:00+03:00",
    "TimeZone": "MSK",
    "Statuses": ["Authorized", "Completed", "Cancelled", "Declined"]
}

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
}

POST /subscriptions/cancel — Отмена подписки

Параметр Где Тип Обяз. Описание
Id body String да Идентификатор подписки

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

{"Id":"sc_cc673fdc50b3577e60eee9081e440"}

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

{"Success":true,"Message":null}

POST /orders/create — Создание счёта со ссылкой на оплату

Формирует ссылку на оплату и при необходимости отправляет её плательщику по e-mail, SMS или Viber.

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

Параметр Где Тип Обяз. Описание
Amount body Number да Сумма платежа
Currency body String нет Валюта, по умолчанию RUB
Description body String да Назначение платежа
Email body String нет E-mail плательщика
RequireConfirmation body Bool нет true — двухстадийная схема
SendEmail body Bool нет Отправить письмо со ссылкой
InvoiceId body String нет Номер заказа
AccountId body String нет Идентификатор пользователя
OfferUri body String нет Ссылка на оферту
Phone body String нет Телефон плательщика
SendSms body Bool нет Отправить SMS со ссылкой
SendViber body Bool нет Отправить сообщение в Viber
CultureName body String нет Язык уведомлений
SubscriptionBehavior body String нет Платёж с подпиской: CreateWeekly, CreateMonthly
SuccessRedirectUrl body String нет Редирект при успешной оплате
FailRedirectUrl body String нет Редирект при неуспешной оплате
JsonData body Json нет Данные транзакции, в том числе для онлайн-чека

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

{
    "Amount":10.0,
    "Currency":"RUB",
    "Description":"Оплата на сайте example.com",
    "Email":"client@test.local",
    "RequireConfirmation":true,
    "SendEmail":false
}

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

{
    "Model": {
        "Id": "gASGZVgUN21hcpPF",
        "Number": 2130,
        "Amount": 10.0,
        "Currency": "RUB",
        "Url": "https://orders.cloudpayments.ru/d/gASGZVgUN21hcpPF"
    },
    "Success": true,
    "Message": null
}

Нюансы

Ошибки

Код Описание
401 Нет заголовка аутентификации или неверные данные
429 Превышено число одновременных запросов
5001 Refer To Card Issuer — отказ эмитента проводить онлайн-операцию
5005 Do Not Honor — отказ эмитента без объяснения причин
5006 Error — отказ сети или неправильный CVV-код
5012 Invalid Transaction — карта не предназначена для онлайн-платежей
5013 Amount Error — слишком маленькая или слишком большая сумма
5014 Invalid Card Number — некорректный номер карты
5030 Format Error — неверно сформирована транзакция на стороне эквайера
5034 Suspected Fraud — подозрение на мошенничество
5041 Lost Card — карта потеряна
5043 Stolen Card — карта украдена
5051 Insufficient Funds — недостаточно средств
5054 Expired Card — карта просрочена или неверный срок действия
5057 Transaction Not Permitted — ограничение на карте
5061 Exceeds Approval Amount — превышена сумма по карте
5065 Exceed Withdrawal Frequency — превышен лимит операций
5082 Incorrect CVV — неверный CVV-код
5091 Timeout — эмитент недоступен
5096 System Error — ошибка банка-эквайера или сети
5204 Unable To Process — операция не может быть обработана
5206 Authentication failed — 3-D Secure авторизация не пройдена
5207 Authentication unavailable — 3-D Secure авторизация недоступна

Ограничения

Источники

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