API и Sandbox для разработчиков: платежные сценарии, вебхуки, тесты

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

API и Sandbox для разработчиков: платежные сценарии, вебхуки, тесты

Table of contents

Введение: зачем разработчику API эквайринга и Sandbox

Современный API эквайринг позволяет гибко подключать онлайн‑оплату на сайт, в мобильное приложение и CRM. Девелоперу он даёт контроль над платежным UX, а бизнесу — масштабируемость, аналитику и снижение издержек. Чтобы интеграция проходила безопасно и без рисков, поставщики предоставляют изолированное окружение — sandbox: это «песочница», где вы воспроизводите успешные оплаты, отказы, 3‑D Secure, возвраты и рекуррентные списания, не затрагивая реальные средства. Такой подход ускоряет выход в прод и помогает пройти требования по безопасности и соответствию.

Полезные материалы по теме:

Архитектура и ресурсы: платеж, захват, возврат, подписка

Большинство платежных API — REST/JSON. Базовые сущности: Payment (платеж), Refund (возврат), Customer (клиент), Token (токен карты/кошелька), Subscription (подписка).

Примеры ключевых эндпоинтов:

Ресурс/метод Путь Назначение
POST /v1/payments Создать платеж (sale или auth)
POST /v1/payments/{id}/capture Захват средств (двухстадийный сценарий)
POST /v1/payments/{id}/cancel Отмена авторизации
GET /v1/payments/{id} Получить статус платежа
POST /v1/refunds Инициировать возврат
POST /v1/customers/{id}/tokens Сохранить токен платёжного инструмента
POST /v1/subscriptions Создать подписку
POST /v1/webhooks Подписаться на события

Типовые статусы: pending, requires_action (нужен 3DS), authorized, succeeded, canceled, refunded, failed. Для идемпотентности используйте заголовок Idempotency-Key.

Пример создания платежа (sale)

curl -X POST https://api.sandbox.payments.example.com/v1/payments \
  -H "Authorization: Bearer sk_test_***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2b9f0b9c-12c3-4f09-ad11-33a1d2f1f555" \
  -d '{
    "amount": {"value": 1990, "currency": "RUB"},
    "capture": true,
    "description": "Оплата заказа #1001",
    "payment_method": {"type": "bank_card", "card": {"number": "4111111111111111", "exp_month": "12", "exp_year": "2030", "cvc": "123"}},
    "confirmation": {"type": "redirect", "return_url": "https://shop.example.com/return"},
    "metadata": {"order_id": "1001"}
  }'

Аутентификация и безопасность: ключи, подписи, соответствие

Платежные сценарии: 1- и 2-стадийные, 3‑D Secure, СПБ

См. общие принципы и витрину методов на странице Онлайн‑эквайринг для сайта.

Webhook платежи: события, подпись, повторная доставка

Подпишитесь на события, чтобы синхронизировать заказы без опроса API:

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

О возвратах и разборе спорных операций читайте в разделе Антифрод, возвраты и чарджбэки.

Рекуррентные платежи API: токенизация, подписки, dunning

Рекуррентные платежи API строятся на токенизации: первая оплата проходит с SCA (CIT), далее — повторные списания без участия клиента (MIT) по токену.

Шаги:

  1. Создайте customer и сохраните payment token (vault).
  2. Проведите первую оплату с 3DS и флагом save_payment_method.
  3. Создайте subscription (period=month, trial=7d, amount=... ).
  4. Обрабатывайте renewal через webhook subscription.renewed: обновляйте баланс подписки, выставляйте счёт или переводите в dunning при отказах.

Подсказки:

Sandbox тест эквайринг: тестовые карты и сценарии

Sandbox — изолированная среда для безопасных экспериментов. Различается только хост:

Тестовые карты и коды исходов (пример):

Номер CVC Результат
4111 1111 1111 1111 123 Успех (succeeded)
4000 0000 0000 0101 123 Требуется 3DS (requires_action)
4000 0000 0000 9995 123 Отказ банка (failed, do_not_honor)

Сценарии, обязательные к прогону:

Ограничения sandbox: реальные фискальные чеки не выбиваются; интеграция с банком/СПБ — эмулирована; лимиты RPS снижены. Для боевых параметров сверьтесь со страницей Сравнение провайдеров эквайринга.

Интеграция платежный шлюз в CMS и бэкенд

Быстрый старт: используйте готовые плагины и SDK. Это сократит время вывода в прод и упростит сопровождение.

Если нужен банк‑эквайер напрямую, изучите особенности: Эквайринг Сбербанка для сайта, Эквайринг Альфа‑Банка для сайта.

Чек-лист тестирования перед запуском

Подробнее о правовых и технических аспектах — в Требования к сайту для эквайринга.

Отладка и типовые ошибки

Код/ситуация Причина Решение
401 unauthorized Неверный/просроченный ключ Проверьте ключ, окружение, права роли
409 conflict Повтор без идемпотентности Добавьте Idempotency-Key
requires_action Нужен 3DS Отправьте клиента на confirmation_url и обработайте возврат
do_not_honor Отказ банка Предложите другой метод/банк, повтор позже
invalid_signature (webhook) Подпись не валидна Сверьте секрет, сырой body, время

См. также антифрод‑практики и работу со спорами: Антифрод, возвраты и чарджбэки.

Как выбрать провайдера и тарифы

На что смотреть помимо API:

Вывод и следующий шаг

API эквайринг и грамотный sandbox тест эквайринг позволяют выстроить стабильный, безопасный и предсказуемый платёжный процесс — от первой оплаты до рекуррентных списаний и возвратов. Внедряйте вебхуки, идемпотентность и мониторинг с первого дня — и вы избежите большинства инцидентов в проде.

Готовы внедрять? Изучите базовые сценарии на странице Онлайн‑эквайринг для сайта и отправьте заявку на Подключить интернет‑эквайринг — поможем с выбором провайдера, интеграцией и тестами в Sandbox.

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