CloudPayments

CloudPayments — карточная касса. База работает через механизм заказов: POST /orders/create создаёт счёт, юзер уходит на hosted-страницу оплаты CloudPayments. Способ оплаты — карта, валюта — только RUB.

Единственный из «карточных» шлюзов базы с возвратами по API: кнопка возврата в кабинете реально возвращает деньги через CloudPayments, а не просто помечает транзакцию.

Что понадобится

Сайт (терминал) в кабинете CloudPayments. Из его настроек:

• Public ID — идентификатор сайта;
• API Secret (пароль для API) — Basic-авторизация запросов и HMAC-подпись уведомлений.

Настройка в кабинете

Кабинет → Платежи → карточка CloudPayments:

Поле	Что это	Обязательное
public_id	Public ID сайта CloudPayments	да
api_secret	Пароль для API — Basic-авторизация и проверка HMAC вебхука	да

Секрет шифруется при сохранении. Включи провайдера тумблером — выключенный отвечает на вебхуки 404. Кнопка «Тест» для CloudPayments API-пробу не выполняет — проверяй первым платежом. Общие поля карточки — в настройках платежей.

Вебхук

В кабинете CloudPayments настрой уведомление Pay на URL:

https://ваш-домен/api/v1/payments/cloudpayments

Тело приходит form-encoded. Подлинность — base64 HMAC-SHA256 от тела запроса с ключом api_secret; CloudPayments передаёт её в заголовках Content-HMAC (по сырому телу) и X-Content-HMAC (по URL-декодированному) — база принимает любую из двух, поэтому прокси, перекодирующий тело, проверку не ломает. Нет заголовка или HMAC не сошёлся → 403.

На валидное уведомление база сама отвечает {"code":0} — без этого CloudPayments ретраит уведомление.

Статусы: Completed/Authorized — оплачен, Declined/Cancelled — отменён, прочее — остаётся в ожидании.

Особенности

• Возвраты по API. Возврат из кабинета дёргает POST /payments/refund по TransactionId платежа. Работает при включённом REFUND_ENABLED — подробности в Возвратах.
• При создании заказа CloudPayments возвращает один id, а в вебхуке приходит другой — TransactionId. База сама переписывает внешний id транзакции на TransactionId из вебхука: именно он нужен API возврата.
• Сохранённые карты и рекурренты для CloudPayments в базе не реализованы — только разовые платежи.
• В заказ уходит AccountId = внутренний ID юзера — по нему удобно искать платежи в кабинете CloudPayments; после оплаты юзер возвращается по return-URL платежа (по умолчанию — в Telegram).
• Опроса статуса по API нет: потерянный вебхук оставляет платёж в ожидании.

Платёж не пришёл?

Реконсилятор проверяет зависшие платежи каждые 5 минут, но CloudPayments не даёт опроса статуса — оплату закрывает только Pay-уведомление. Проверь его URL и формат — разбор доставки в разделе Вебхуки.