Интеграция платежей через API: пошаговое руководство

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

Интеграция платежей через API: пошаговое руководство

Table of contents

Что такое платеж через API и когда он нужен

Платеж через API — это программная передача данных о списании средств напрямую между вашим сервером и провайдером эквайринга или агрегатором. Такая интеграция платежей API обеспечивает гибкость: вы контролируете логику оформления заказа, отображение статусов, управление возвратами и последующими списаниями. API прием платежей особенно актуален для маркетплейсов, SaaS‑платформ, мобильных приложений и интернет‑магазинов с кастомным UI/UX.

Основные преимущества:

Когда стоит выбрать API‑модель:

Схема платежного потока

Ниже — типовая схема платежного потока для карт и альтернативных методов.

Краткая последовательность:

  1. Создание платежа (order) на вашем бэкенде.
  2. Отправка запроса в провайдер: «создание платежа через API» с суммой, валютой, описанием и параметрами возвратов/подписок.
  3. Провайдер возвращает состояние: требуется 3‑D Secure подтверждение, редирект, или мгновенное подтверждение.
  4. Клиент проходит аутентификацию (3‑D Secure/SDK/редирект).
  5. Провайдер завершает авторизацию/списание и отправляет webhook.
  6. Ваш бэкенд фиксирует статус, обновляет заказ и показывает результат пользователю.

Выбор провайдера и модели интеграции

Выбор провайдера влияет на комиссии, конверсию, поддержку методов оплаты и сложность внедрения. Начните с оценки модели интеграции и требований PCI DSS.

Варианты интеграции:

Модель Что это Когда выбирать 3‑D Secure Нагрузка по PCI
Redirect/Hosted Page Клиент временно уходит на платежную страницу провайдера Быстрый старт, минимум комплаенса Обрабатывается провайдером Низкая
Hosted Fields Поля карты в iframe провайдера, UI контролируете вы Компромисс UX и безопасности Обрабатывается провайдером Средняя
Full API (own form) Вы собираете данные карты и шифруете Максимальный контроль и кастом Отправляете на 3‑D Secure сами Высокая (PCI DSS SAQ D)

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

Требования к безопасности и 3‑D Secure подтверждение

При работе с картами учитывайте PCI DSS и SCA/3‑D Secure. 3‑D Secure подтверждение снижает мошенничество и переносит ответственность на эмитента при соблюдении правил. В зависимости от провайдера вы получите URL для редиректа, challenge‑поток либо параметры для SDK.

Подготовка окружения и тестирование

Перед продакшеном разверните окружения DEV/STAGE и подключите песочницу провайдера.

Пошаговая интеграция: создание, подтверждение, webhooks

Ниже — базовый сценарий для карт. Реальные поля и эндпойнты смотрите в документации выбранного провайдера.

Шаг 1. Создание платежа через API

В запросе указывайте сумму, валюту, описание заказа, callback/webhook URL, а также уникальный ключ идемпотентности.

curl -X POST https://api.provider.example/payments \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Idempotency-Key: 9f8d2e4c-1a2b-4bcd-9e01-1234567890ab" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {"value": "1990.00", "currency": "RUB"},
    "capture": true,
    "description": "Order #4312",
    "confirmation": {"type": "redirect", "return_url": "https://shop.example/thanks"},
    "metadata": {"order_id": "4312"},
    "receipt": {"customer": {"email": "user@example.com"}},
    "webhook_url": "https://shop.example/webhooks/payments"
  }'

Ответ может содержать:

Шаг 2. Проведение 3‑D Secure/авторизации

Шаг 3. Обработка webhooks платежи После авторизации провайдер отправит webhook о финальном статусе (succeeded/canceled). В обработчике:

Шаг 4. Повторные запросы и идемпотентность Сохраняйте Idempotency-Key и payment_id, чтобы безопасно ретраить запросы при сетевых сбоях. Подробнее — в разделе ниже и в гайде: Вебхуки и идемпотентность.

Шаг 5. Частичная/полная отмена и возврат На этапе пост‑платежных операций используйте API для отмены авторизации (reversal) или возврата (refund). См. детали: Возвраты и реверсалы.

Идемпотентность API и защита от дублей

Идемпотентность API гарантирует, что повторная отправка одного и того же запроса не создаст дубликатов платежей. Практика:

Разработайте единый паттерн для вебхуков и повторов запросов: Вебхуки и идемпотентность.

Возвраты и отмены

Возврат платежа API позволяет вернуть средства полностью или частично. Отличайте:

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

Подробности и примеры статусов: Возвраты и реверсалы.

Повторяющиеся платежи и токенизация

Для подписок и регулярных списаний используйте сохраненные токены (card‑on‑file). Базовый поток:

Важные моменты:

Шаблоны и советы по подпискам: Повторяющиеся списания и подписки.

Сверка платежей и мониторинг

Даже идеальная интеграция платежей API без качественной сверки будет уязвима к расхождениям. Настройте ежедневную сверку реестров провайдера с вашей БД.

Чек‑лист перед выходом в прод

Заключение и следующий шаг

Интеграция платежей API дает вам контроль над UX, автоматизацию финансовых процессов и гибкость масштабирования. Начните с тестов в песочнице, сформируйте схему платежного потока под ваш продукт, подключите 3‑D Secure подтверждение и выстройте надежную работу webhooks и идемпотентности.

Готовы внедрять? Выберите провайдера (YooMoney, Сбербанк, T‑Bank, Belarusbank), проверьте требования безопасности PCI DSS и 3‑D Secure и запустите первые транзакции в песочнице. Если потребуется расширенная логика (подписки, возвраты, сверка), используйте наши шаблоны: вебхуки и идемпотентность, возвраты и реверсалы, подписки, сверка и аналитика.

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