CloudPayments — платежный провайдер для приема карт, СБП и международных платежей. Интерфейсы предоставляются как через виджет и мобильные SDK, так и через REST на хосте api.cloudpayments.ru (часто ищут как «api cloudpayments ru»). Если вы только начинаете, посмотрите краткое введение — что такое CloudPayments — и оцените тарифы и комиссии.
CloudPayments API позволяет:
Официальная cloudpayments документация доступна в «cloudpayments docs ru». Ниже — концентрированный обзор, лучшие практики и разбор типичных ошибок.
Аутентификация к REST обычно выполняется через Basic Auth c парой publicId:apiSecret. Пример заголовка:
Важно:
Ниже — схематичная выжимка типовых вызовов 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 — см. интеграции и плагины.
Одностадийная (Charge): деньги списываются сразу. Подходит для цифровых товаров и мгновенной доставки.
Двухстадийная (Auth → Confirm/ Void): сначала блокировка суммы, затем подтверждение. Удобно для предзаказов, доставки, динамических цен.
Советы:
CloudPayments поддерживает токенизацию карты и последующие списания без ввода реквизитов.
Рекомендации:
При работе в РФ необходимо передавать данные для чека: позиции, НДС, признак агента, контакты покупателя. В CloudPayments это может делаться либо отдельным /kkt/ вызовом, либо в составе платежа (Receipt/Items). Подробно — в разделе чеки и касса.
Советы:
Комбинируйте методы оплаты (карта, СБП, invoice), чтобы повысить конверсию.
CloudPayments отправляет серверные уведомления (webhooks) о событиях — «Check» (предпроверка заказа), «Pay» (успех), «Fail» (ошибка) и др. Ключевые моменты:
Если есть расхождения между вебхуком и UI, делайте проверку статуса через API — см. проверка платежа.
Ниже — обобщение распространенных проблем. Полный справочник — в разделе коды ошибок 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).
Если заметили расхождение с cloudpayments docs, уточняйте актуальные спецификации — «cloudpayments docs ru» регулярно обновляются.
Ниже схематичный пример одностадийного списания через 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 API сочетает удобный виджет, мобильные SDK и REST на api.cloudpayments.ru. Следуя лучшим практикам (валидация подписи вебхуков, корректная обработка ошибок, логирование, KKT, UX‑fallback с капчей), вы получите стабильную интеграцию с высокой конверсией. Нужна помощь с внедрением или отладкой cloudpayments api? Обратитесь в поддержку или начните с наших гайдов по проверке платежей и возвратам.