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

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

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

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

Что выбрать и как подключить: Онлайн‑эквайринг для сайта и Подключить интернет‑эквайринг
Юридические и техтребования: Требования к сайту для эквайринга и Безопасность: PCI DSS, 54‑ФЗ, 152‑ФЗ

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

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

Схема API эквайринга

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

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

Ресурс/метод	Путь	Назначение
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"}
  }'

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

Доступ: секретные ключи (server‑side) и публичные (client‑side). Для бэкенда используйте только секретный ключ, храните в Vault/KMS, регулярно ротируйте.
Подпись запросов и вебхуков: HMAC‑SHA256 по телу и таймстемпу. Проверяйте X-Signature и X-Timestamp, отклоняйте просроченные (>5 мин).
Сетевые практики: TLS 1.2+, SNI, возможна mTLS/allowlist исходящих IP.
Данные карт: не храните PAN/CVC у себя — используйте токенизацию. Соответствие PCI DSS, 54‑ФЗ и 152‑ФЗ обязательно. Фискализация чеков подключается через ОФД/кассу.

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

Одностадийный (sale): списание сразу после успешной авторизации. Подходит для цифровых товаров.
Двухстадийный (auth/capture): блокировка сначала, списание — после отгрузки. Полезно для логистики и предзаказов.
3‑D Secure / SCA: при статусе requires_action перенаправляйте покупателя на подтверждение (redirect или challenge SDK). После верификации запрос завершится в succeeded/authorized.
Альтернативные методы: СБП/QR, Apple Pay/Google Pay, кошельки. Транзакции зачастую завершаются быстрее, но проверьте статусы и окна таймаута в sandbox.

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

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

Диаграмма webhook платежей

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

payment.succeeded / payment.canceled / payment.failed
payment.authorized / payment.captured
refund.succeeded / refund.failed
subscription.created / subscription.renewed / subscription.canceled

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

Подпись: проверяйте X-Signature (HMAC по сырому телу). Храните несколько актуальных секретов для ротации.
Повторы: вебхуки повторяются с увеличением интервалов (экспоненциальный бэкофф) до N часов. Обрабатывайте идемпотентно (ключ из event.id).
SLA: отвечайте 200 OK в течение ≤2–3 секунд, тяжёлую обработку выносите в очередь.
Диагностика: логируйте request_id/trace_id, храните последние 7–30 дней событий.

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

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

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

Шаги:

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

Подсказки:

Dunning: план повторных попыток 1h / 24h / 72h; уведомляйте клиента.
Маскирование PAN, соблюдение PCI, хранение только токенов. Подробности — в Безопасность: PCI DSS, 54‑ФЗ, 152‑ФЗ.

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

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

API: https://api.sandbox.payments.example.com
Кабинет/вебхуки: https://dashboard.sandbox.payments.example.com

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

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

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

Создание/захват/отмена двухстадийного платежа.
3DS challenge и последующий статус.
Полный/частичный возврат.
Вебхуки: имитация повтора, проверка подписи, обработка идемпотентности.
Подписка: успешное обновление и отказ с dunning.

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

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

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

CMS плагины: WordPress/WooCommerce, 1C‑Битрикс, OpenCart, Tilda, CS‑Cart
Выбор движка и совместимость с платежами: Выбор движка для сайта с эквайрингом
Backend: оформляйте серверный контроллер «создать платеж», страницу return_url и endpoint для вебхуков. Учтите очереди и ретраи.

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

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

Идемпотентность: повторные POST не создают дублей.
Все статусы платежа корректно маппятся на статусы заказа.
3DS: UX отрабатывает во всех браузерах и на мобильных.
Вебхуки: верификация подписи, повторы, устойчивость к порядку доставки.
Возвраты: full/partial, возврат после захвата и после отмены.
Подписки: создание, продление, отмена, dunning‑процедуры.
Фискализация: чек/ККТ по 54‑ФЗ, корректные позиции и ставки НДС.
Логи и мониторинг: запросы к API, webhooks, алерты по SLA.
Нагрузочное тестирование: RPS и время ответа.

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

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

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

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

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

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

Доступность и SLA, скорость авторизации, доля 3DS.
Методы оплаты: карты, СБП, Apple/Google Pay, BNPL.
Комиссии и скрытые издержки: изучите Тарифы и комиссии эквайринга.
Поддержка SDK, готовые плагины, логирование вебхуков.
Юр‑часть и финмодели: прямой банк vs. платёжный провайдер — сравнение на странице Сравнение провайдеров эквайринга.

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

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

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

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