Stripe API

Основные объекты API

• Charge — устаревший объект, представляющий единичное списание средств с карты. В современных версиях API заменён на PaymentIntent.
• PaymentIntent — основной объект для обработки платежа. Он управляет всем жизненным циклом транзакции: от создания до подтверждения и завершения. Содержит информацию о сумме, валюте, статусе, методе оплаты и связанных событиях.
• SetupIntent — объект, используемый для сохранения данных платёжного метода (например, карты) для будущих платежей, без фактического списания средств в момент сохранения.
• PaymentMethod — объект, представляющий конкретный способ оплаты: банковскую карту, цифровой кошелёк (Apple Pay, Google Pay), банковский перевод (ACH, SEPA) и другие.
• Customer — объект, представляющий плательщика. Позволяет привязывать к нему несколько PaymentMethod, управлять подписками и историей платежей.
• Subscription — объект для управления регулярными платежами (подписками). Содержит информацию о плане, периоде, статусе (active, past_due, canceled) и связанных инвойсах.
• Invoice — объект, представляющий счёт на оплату. Автоматически генерируется для подписок или может быть создан вручную.
• Refund — объект для возврата средств по завершённому платежу.
• WebhookEndpoint — объект для настройки вебхуков (HTTP-уведомлений), которые Stripe отправляет на указанный URL при наступлении определённых событий (например, payment_intent.succeeded, charge.refunded).

Жизненный цикл платежа через PaymentIntent

1. Создание PaymentIntent: Сервер приложения отправляет POST-запрос на /v1/payment_intents с указанием суммы, валюты и, опционально, Customer ID. Stripe возвращает объект PaymentIntent со статусом requires_payment_method.
2. Сбор платёжных данных на клиенте: Используя Stripe.js или Stripe Elements, клиентский код собирает данные карты и отправляет их напрямую в Stripe, получая взамен токен или PaymentMethod ID. Это минимизирует передачу чувствительных данных через сервер приложения (PCI DSS compliance).
3. Подтверждение платежа: Клиентский код вызывает метод stripe.confirmCardPayment() с client_secret из PaymentIntent. Stripe обрабатывает платёж и, в случае успеха, меняет статус на succeeded. Если требуется 3D Secure, статус временно становится requires_action, и клиент перенаправляется на страницу аутентификации.
4. Обработка результата: Сервер приложения может получить уведомление через вебхук (например, payment_intent.succeeded) или опросить статус PaymentIntent через GET-запрос.

Классификация методов оплаты

Stripe API поддерживает сотни различных платёжных методов, которые можно разделить на несколько категорий:

• Карточные методы: Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay.
• Цифровые кошельки: Apple Pay, Google Pay, Microsoft Pay, Samsung Pay.
• Банковские переводы: ACH (США), SEPA (Европа), BACS (Великобритания), FPX (Малайзия), iDEAL (Нидерланды).
• Локальные способы оплаты: Alipay (Китай), WeChat Pay (Китай), Konbini (Япония), Boleto (Бразилия), OXXO (Мексика), PayNow (Сингапур).
• Криптовалюты: USDC (стабильная монета) на блокчейнах Ethereum, Solana и Polygon.
• Платёжные ссылки и счета: Invoice, Payment Links.

Версионирование и обратная совместимость

Stripe API использует дату версии в качестве номера версии (например, 2023-10-16, 2022-11-15). Каждая новая версия может содержать как обратно совместимые изменения (добавление новых полей), так и ломающие изменения (удаление или переименование полей). Разработчики могут зафиксировать конкретную версию API в настройках аккаунта Stripe или передавать заголовок Stripe-Version в каждом запросе. Stripe гарантирует поддержку старых версий API в течение как минимум двух лет с момента выпуска новой версии.

Клиентские библиотеки и SDK

Stripe предоставляет официальные клиентские библиотеки для следующих языков и платформ:

• Серверные: Ruby (stripe-ruby), Python (stripe-python), PHP (stripe-php), Java (stripe-java), Node.js (stripe-node), Go (stripe-go), .NET (stripe-dotnet).
• Клиентские: JavaScript (Stripe.js), React Native (stripe-react-native), iOS (Stripe iOS SDK), Android (Stripe Android SDK).

Библиотеки автоматически обрабатывают повторные попытки при временных ошибках, сериализацию/десериализацию JSON и управление версиями API.

Ограничения и критикова

Основные ограничения Stripe API включают:

• Региональные ограничения: Stripe доступен для использования только в определённых странах. В России, Беларуси и ряде других стран регистрация новых аккаунтов невозможна, а существующие аккаунты были заблокированы или ограничены.
• Комиссии: Stripe взимает комиссию за транзакцию (обычно 2,9% + 0,30 USD для карточных платежей), что может быть выше, чем у некоторых локальных платёжных шлюзов.
• Сложность для простых сценариев: Несмотря на декларируемую простоту, реализация сложных сценариев (многошаговая аутентификация, частичные возвраты, мульти-валютные операции) требует глубокого понимания API и может быть нетривиальной.
• Зависимость от стороннего сервиса: Полная зависимость от инфраструктуры Stripe — при сбоях на стороне Stripe (которые случались в истории компании) приём платежей на сайтах клиентов полностью останавливается.

Критика в адрес Stripe API также связана с непрозрачностью политики заморозки счетов и блокировки аккаунтов без предварительного уведомления, что особенно часто встречалось у стартапов и проектов с высоким риском возвратов.

Безопасность и PCI DSS

Stripe API спроектирован таким образом, чтобы минимизировать объём чувствительных платёжных данных, проходящих через серверы разработчика. Использование Stripe.js и Stripe Elements позволяет собирать данные карт непосредственно на стороне Stripe, что освобождает разработчика от необходимости проходить полную сертификацию PCI DSS (достаточно заполнить анкету SAQ A). Для дополнительной безопасности Stripe поддерживает 3D Secure 2, токенизацию данных карт и шифрование всех запросов по протоколу TLS 1.2+.

Источники

• Официальная документация Stripe API (stripe.com/docs/api)
• Документация Stripe по безопасности и PCI DSS (stripe.com/docs/security)
• История версий Stripe API (stripe.com/docs/upgrades)
• Руководство по миграции с Charges на PaymentIntents (stripe.com/docs/payments/payment-intents/migration)