CloudPayments API: обзор, лучшие практики и частые ошибки

Что такое CloudPayments API

CloudPayments — платежный провайдер для приема карт, СБП и международных платежей. Интерфейсы предоставляются как через виджет и мобильные SDK, так и через REST на хосте api.cloudpayments.ru (часто ищут как «api cloudpayments ru»). Если вы только начинаете, посмотрите краткое введение — что такое CloudPayments — и оцените тарифы и комиссии.

CloudPayments API позволяет:

принимать платежи «в один клик» и через 3‑D Secure;
выполнять двухстадийные операции (предавторизация/подтверждение);
управлять подписками и токенами карт;
оформлять возвраты и отмены;
отправлять фискальные чеки в ОФД;
работать с СБП и выставлением счетов.

Официальная cloudpayments документация доступна в «cloudpayments docs ru». Ниже — концентрированный обзор, лучшие практики и разбор типичных ошибок.

Public ID, API‑ключи и аутентификация

Public ID — публичный идентификатор магазина для фронтенда (виджет/SDK). Где взять и как подключить виджет — в материале Public ID CloudPayments.
API Secret — секрет для сервер‑к‑серверу запросов и проверки подписи вебхуков. Доступен в личном кабинете (см. также merchant вход).

Аутентификация к REST обычно выполняется через Basic Auth c парой publicId:apiSecret. Пример заголовка:

Получить CloudPayments бесплатно

Authorization: Basic base64(publicId:apiSecret)

Важно:

Никогда не вшивайте API Secret в клиентский код.
Храните ключи в секрет‑хранилище, регулярно ротируйте.
Разделяйте тестовые и боевые ключи.

Основные эндпоинты и сценарии

Ниже — схематичная выжимка типовых вызовов CloudPayments API (для точных параметров см. cloudpayments docs):

Эндпоинт (пример)	Метод	Назначение
/payments/charge	POST	Одностадийная оплата (списание сразу)
/payments/auth	POST	Двухстадийная предавторизация
/payments/confirm	POST	Подтверждение удержанной суммы
/payments/void	POST	Отмена предавторизации
/payments/refund	POST	Частичный/полный возврат (см. возврат денег)
/payments/find	GET/POST	Поиск статуса операции (см. проверка платежа)
/subscriptions/create	POST	Создание подписки
/subscriptions/cancel	POST	Отмена подписки (см. отмена подписки)
/kkt/receipt	POST	Фискализация чеков (см. чеки/касса)
/sbp/...	—	Операции СБП (см. CloudPayments СБП)

Кроме REST, доступны виджет и мобильные CloudPayments SDK (iOS/Android), а также плагины CMS — см. интеграции и плагины.

Одностадийная vs двухстадийная оплата

Одностадийная (Charge): деньги списываются сразу. Подходит для цифровых товаров и мгновенной доставки.

Двухстадийная (Auth → Confirm/ Void): сначала блокировка суммы, затем подтверждение. Удобно для предзаказов, доставки, динамических цен.

Советы:

Для 3‑D Secure сценариев используйте виджет/SDK — они умеют корректно отражать challenge‑шаги.
Перед подтверждением двухстадийной операции сверяйте сумму и статус платежа (по TransactionId/InvoiceId) — см. проверка платежа.

Подписки и рекуррентные списания

CloudPayments поддерживает токенизацию карты и последующие списания без ввода реквизитов.

Создание подписки: сохраняете токен (или создаете subscriptionId) после первого успешного платежа.
Рекуррент: запускаете списания по расписанию, передавая сумму и идентификаторы клиента (AccountId) и подписки.
Отмена: реализуйте кнопку «Отписаться» и вызывайте отмену — см. как отменить подписку и как отвязать карту.

Рекомендации:

Уведомляйте клиента заранее о предстоящем списании.
Предусматривайте grace‑период и повторные попытки списания при временных отказах (insufficient funds, 3DS required и т. п.).

Фискализация чеков (ККТ)

При работе в РФ необходимо передавать данные для чека: позиции, НДС, признак агента, контакты покупателя. В CloudPayments это может делаться либо отдельным /kkt/ вызовом, либо в составе платежа (Receipt/Items). Подробно — в разделе чеки и касса.

Советы:

Присылайте валидные ставки НДС и корректные суммы по позициям (итог должен совпадать с Amount).
Если отправляете чек после оплаты — обрабатывайте статус доставки чека и ретраи при временных сбоях ОФД.

СБП и международные платежи

СБП: быстрые переводы по QR/ссылке, часто выше конверсия на мобайле. Смотрите CloudPayments СБП.
Международные платежи: поддержка разных валют и карт зарубежных эмитентов — нюансы и ограничения описаны в международные платежи.

Комбинируйте методы оплаты (карта, СБП, invoice), чтобы повысить конверсию.

Вебхуки, безопасность и подпись

CloudPayments отправляет серверные уведомления (webhooks) о событиях — «Check» (предпроверка заказа), «Pay» (успех), «Fail» (ошибка) и др. Ключевые моменты:

Подпись: каждое уведомление подписывается HMAC‑SHA256 по телу запроса секретным ключом. Проверяйте заголовок с подписью (часто именуется Content-HMAC) и отклоняйте неподтвержденные запросы.
Ответы: возвращайте HTTP 200 быстро; сложную бизнес‑логику выносите асинхронно.
Идемпотентность: по TransactionId/InvoiceId обеспечьте «неповторяемость» изменений состояния заказа.
Безопасность: принимайте уведомления только по HTTPS, логируйте заголовки/тело, ограничивайте доступ по IP/фаерволу и rate limit.

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

Лучшие практики интеграции

Валюта и суммы: передавайте Amount как десятичное число (2 знака), не теряйте копейки при сериализации.
Поля заказа: заполняйте InvoiceId (ваш ID), AccountId (ID клиента), Description, а также JsonData для метаданных.
Ретраи и таймауты: ставьте таймауты 20–60 cек. На повтор подачи платежа всегда предваряйте проверкой статуса.
Логи: логируйте requestId/transactionId, ReasonCode и тело ответов для отладки cloudpayments error.
UX: обрабатывайте ответы виджета, показывайте причину отказа и давайте альтернативы (СБП, другая карта).
Captcha: при аномальной активности может появиться «captcha от cloudpayments». Предусмотрите контейнер в интерфейсе и fallback.
Конфиденциальность: никогда не храните CVV, соблюдайте PCI DSS.

Частые ошибки и коды CloudPayments

Ниже — обобщение распространенных проблем. Полный справочник — в разделе коды ошибок CloudPayments.

Ошибка/ReasonCode	Что означает	Что делать
ValidationError	Неверные/неполные поля запроса	Проверьте схему запроса, типы данных, валюту, сумму
3DSRequired/3DSFailed	Нужна аутентификация 3‑D Secure или она не пройдена	Используйте виджет/SDK; повторите платеж после успешного 3DS
InsufficientFunds	Недостаточно средств	Предложите другую карту/метод (например, СБП)
ExpiredCard	Истек срок	Обновите карту, отвяжите старую — см. как отвязать карту
DoNotHonor/Declined	Банк отклонил	Предложите альтернативу, посоветуйте связаться с банком
PaymentLimitExceeded	Превышен лимит	Уменьшите сумму или попробуйте позже/другую карту
TokenExpired	Токен/подписка недействительны	Переоформите подписку, повторно токенизируйте карту
CaptchaRequired	Провайдер требует капчу	Отобразите капчу и повторите попытку
AlreadyConfirmed/Duplicate	Повтор подтверждения	Проверьте статус через API; не подтверждайте дважды
FraudSuspected	Риск‑фильтр	Проверьте данные клиента, предложите СБП или другой метод

Примечание по HTTP: успешный HTTP 200 не гарантирует, что платеж прошел — проверяйте флаг Success и ReasonCode. Неуспехи авторизации могут возвращаться в 200 с Success=false (особенность API CloudPayments).

Тестирование и отладка

Используйте тестовый режим и карточные номера из раздела тестовые карты и демо для имитации Success/Fail/3DS.
Прогоняйте критические сценарии: charge, auth/confirm/void, refund, chargeback‑подобные кейсы, подписки, СБП.
Сверяйте статусы в личном кабинете и через API.

Если заметили расхождение с cloudpayments docs, уточняйте актуальные спецификации — «cloudpayments docs ru» регулярно обновляются.

Пример запроса к API

Ниже схематичный пример одностадийного списания через api.cloudpayments.ru. Обязательно сверяйте параметры с актуальной cloudpayments документацией.

curl -X POST \
  https://api.cloudpayments.ru/payments/charge \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic BASE64(publicId:apiSecret)" \
  -d '{
    "Amount": 990.00,
    "Currency": "RUB",
    "InvoiceId": "ORD-100500",
    "Description": "Оплата подписки",
    "AccountId": "user_123",
    "IpAddress": "203.0.113.10",
    "Token": "CARD_TOKEN_OR_PAN_DATA",
    "JsonData": {"plan": "pro", "source": "landing"}
  }'

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

{
  "Success": true,
  "Model": {
    "TransactionId": 123456789,
    "Status": "Completed",
    "Amount": 990.00,
    "Currency": "RUB"
  }
}

При Success=false смотрите ReasonCode/Message и действуйте по таблице выше.

Полезные ссылки и куда обращаться

Как подключить провайдера: как подключить CloudPayments
Страница входа и кабинет: merchant вход, мой CloudPayments
Возвраты, отмены и подписки: возврат денег, отмена подписки
Справочник ошибок: коды ошибок CloudPayments
СБП и международные: CloudPayments СБП, международные платежи
Интеграции, тарифы и отзывы: интеграции и плагины, тарифы, отзывы
Официальные ресурсы: официальный сайт и логотип
Поддержка: контакты поддержки

Итоги: CloudPayments API сочетает удобный виджет, мобильные SDK и REST на api.cloudpayments.ru. Следуя лучшим практикам (валидация подписи вебхуков, корректная обработка ошибок, логирование, KKT, UX‑fallback с капчей), вы получите стабильную интеграцию с высокой конверсией. Нужна помощь с внедрением или отладкой cloudpayments api? Обратитесь в поддержку или начните с наших гайдов по проверке платежей и возвратам.

Получить CloudPayments бесплатно