Интеграция со Stripe: архитектура, безопасность и типичные ошибки

В перечне задач платежная интеграция обманчиво похожа на небольшую функцию: показать форму, списать средства с карты и сообщить об успехе. На деле это распределенный финансовый процесс. Покупатель может пройти аутентификацию и вернуться позже; банк — отклонить или подтвердить операцию с задержкой; браузер — закрыться после списания, но до получения ответа; сеть — повторить тот же запрос; возврат может быть частичным, а оспаривание — поступить через несколько недель после исполнения заказа. Самое сложное — определить, какое событие должно ровно один раз изменить состояние хозяйственной операции.

Stripe предоставляет платежные компоненты, готовые и встроенные интерфейсы, средства регулярных начислений, инфраструктуру для торговых площадок и инструменты эксплуатации. При этом Stripe не решает, когда заказ следует оплатить, исполнить, разрешить к возврату, признать просроченным или закрыть. Это правила продукта и бухгалтерского учета. Рабочая интеграция должна связывать объекты Stripe с внутренним регистром заказов, счетов, прав доступа, выплат и корректировок.

Здесь разработка платежной функции представлена как задача системного проектирования. Руководство охватывает модель состояний, границы доверия, PaymentIntents, Checkout и Elements, доставку веб-уведомлений, подписки, Connect, безопасность, испытания, сверку и действия сотрудников в случаях, когда автоматизация не может разрешить финансовое исключение.

Сначала спроектируйте схему движения средств

Сначала начертите движение ценности и ответственности. Определите покупателя, юридического продавца, поставщика товара или услуги, платформу, платежного оператора, налоговый орган и банк. Зафиксируйте, кто устанавливает цену, принимает условия, поставляет товар, выставляет счет, финансирует возврат, покрывает отрицательный остаток, отвечает на оспаривание и владеет записью об операции. От этой модели зависит выбор продукта Stripe; сам продукт ее не заменит.

В простом магазине процесс может состоять из одного платежа и последующего исполнения заказа. Продукт SaaS добавляет пробные периоды, пропорциональный перерасчет, повышение тарифа, неудачные продления, зачеты и изменение прав доступа. Торговой площадке нужны подключение связанных учетных записей, проверка их возможностей, распределение средств, комиссии платформы, резервы, возвраты, оспаривания и выплаты. Мобильный продукт также должен соблюдать правила платформы, действующие для соответствующего товара и региона.

До начала реализации определите страны, валюты, способы оплаты, юридические лица для расчетов, налоговый порядок, правила возврата, названия операций в выписке и требования к доказательствам. Убедитесь, что Stripe и нужные продукты доступны в каждой стране деятельности. После этого смоделируйте весь жизненный цикл: отказ от покупки, аутентификацию, отложенное подтверждение, частичное исполнение, отмену, возврат, оспаривание, неудачную выплату и закрытие учетной записи.

• Клиентское приложение: показывает управляемые Stripe платежные поля, отправляет аутентифицированный хозяйственный запрос, при необходимости подтверждает операцию и отображает состояние, полученное с сервера.

• Платежный API: проверяет личность, каталог, сумму, валюту, налог, получателя и разрешения, прежде чем отправить идемпотентную команду Stripe.

• Учетная система: связывает внутренние заказы, счета и права доступа с объектами Stripe и фиксирует каждый допустимый переход хозяйственного состояния.

• Stripe: согласует правила способов оплаты, аутентификацию, авторизацию, завершение списания, объекты регулярных начислений, остатки, переводы, возвраты и оспаривания.

Сделайте проверенные веб-уведомления надежным источником состояния платежа

Веб-уведомления образуют надежный мост между асинхронным состоянием Stripe и вашей системой. Выделите для них отдельную конечную точку HTTPS, сохраняйте исходное тело запроса, проверяйте подпись Stripe по секрету конечной точки и отклоняйте просроченные или недействительные запросы. Для испытательной и рабочей сред используйте разные секреты. После надежного приема быстро возвращайте успешный ответ, а исполнение заказа и другую медленную работу передавайте в очередь.

Исходите из того, что каждое уведомление может прийти как минимум один раз, с задержкой и в порядке, отличном от ожидаемого. Сохраняйте идентификатор события с ограничением уникальности, но сделайте идемпотентным и сам переход хозяйственного состояния: один и тот же платеж или счет может появиться в нескольких связанных типах событий. Блокируйте соответствующий совокупный объект или обновляйте его по условию, при необходимости упорядочения получайте самый свежий объект Stripe и применяйте переход лишь тогда, когда текущее состояние его допускает.

Ведите журнал приема со временем поступления, состоянием обработки, числом попыток, идентификаторами связи и очищенным от чувствительных данных описанием ошибки. Оповещайте ответственных о неудачной проверке подписи, возрасте самого старого необработанного события, повторных ошибках процедуры обработки и расхождениях между Stripe и вашими записями. Создайте средство безопасной повторной обработки, устойчивое к дубликатам. Периодическая сверка все равно необходима, ведь ни один поток событий не может быть единственным доказательством для закрытия учетного периода.

Защитите весь платежный контур

PaymentIntent обозначает попытку получить определенную сумму в заданной валюте за покупку. Stripe советует создавать один PaymentIntent для каждого заказа или сеанса покупателя и обновлять его по мере оформления. Повторное использование сохраняет историю попыток и позволяет Stripe согласовывать требования к аутентификации и способу оплаты, допуская при этом не более одного успешного списания для данного намерения.

Создавайте его на сервере после проверки заказа. Храните в своей базе внутренний идентификатор заказа, а метаданные используйте лишь для связи нечувствительных сведений. Передавайте секрет клиента только предназначенному сеансу покупателя, никогда не записывайте его в журнал и не добавляйте в общедоступный адрес. Рассматривайте состояния как конечный автомат: до успеха или отмены платеж может потребовать способ оплаты, подтверждение, действие покупателя, завершение списания, асинхронную обработку или новую попытку.

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

Выбирайте способ интеграции по тому, какую часть системы команда готова поддерживать самостоятельно. Размещенный в Stripe Checkout обычно служит лучшим исходным вариантом, когда скорость внедрения, охват способов оплаты, локализация, приспособление к размеру экрана и меньшие расходы на сопровождение важнее полностью особого процесса. Embedded Checkout оставляет пользователя на вашей странице, но сохраняет готовый платежный путь. Payment Element дает больше свободы в компоновке, тогда как Stripe по-прежнему отвечает за поля с чувствительными данными и актуальное представление способов оплаты.

Выбор уже не сводится к противопоставлению «перенаправление или собственная форма». Checkout Sessions поддерживает размещенный, встроенный подход и построение из собственных компонентов. Сравните поддержку налогов, скидок, доставки, подписок, сохраненных способов, электронных кошельков, местных способов оплаты, мобильных SDK, доступности, аналитики и будущих изменений. Проверьте полный путь на настоящих поддерживаемых устройствах: ввод и проверку данных, аутентификацию, возврат, повторную попытку и отмену.

Отдавайте предпочтение решению, которое устраняет неспецифичную для вашего продукта платежную работу. Любое особое поведение создает длительную ответственность: необходимо проверять доступность, изменения браузеров, локализацию, восстановление после ошибок, работу кошельков и каждый новый способ оплаты. Не помещайте данные продукта в чувствительные поля, показывайте условия до подтверждения, предотвращайте двойную отправку и сообщайте об ожидании, если результат еще формируется асинхронно. Страница успешной операции должна получать текущее состояние с сервера; она не должна объявлять успех на основании параметра адреса.

Платеж завершен тогда, когда проверенное финансовое состояние совпадает с вашей хозяйственной записью, а не тогда, когда браузер открыл страницу успеха.

— GARNO.TECH Engineering

Управляйте подписками как финансовыми операциями

Регулярное выставление счетов — это длительные отношения с клиентом, обладающие собственным состоянием, а не списание с карты по расписанию. Смоделируйте каталог, версии Price, расчетный период, пробный срок, время выставления счета, налоги, купоны, зачеты, пропорциональный перерасчет, отмену, приостановку, восстановление после неудачного платежа и точное правило предоставления или прекращения права доступа. Доступ к продукту должен определяться вашими проверенными правилами о подписке и счете, а не ответом браузера или одним отдельным событием.

Сохраняйте неизменную историю коммерческих условий. Когда цена меняется, создавайте новый Price и переводите клиентов по четким правилам, не переписывая смысл старых счетов. Определите, вступает ли повышение тарифа в силу немедленно, как объясняется пропорциональный перерасчет, что происходит в конце периода, как измеряется и исправляется использование и как финансовая служба учитывает зачеты. Для зависящих от времени случаев применяйте испытательные часы Stripe, где они поддерживаются, но отдельно проверяйте собственное время, периодические задания и правила доступа.

Stripe Connect добавляет в систему несколько предприятий и остатков средств. Выбирайте модель списания и движения денег в соответствии с юридической и операционной ответственностью: кто является юридическим продавцом, кто платит комиссии, финансирует возвраты, отвечает за оспаривания и отрицательные остатки и когда средства становятся доступными для выплаты. Оформите подключение учетной записи, требования к идентификации, возможности, резервы, переводы, обратные операции, неудачные выплаты и отключение как отдельные процессы. Финансовой службе и поддержке нужна сквозная связь от платежа покупателя через комиссии платформы и переводы до окончательной выплаты.

Ошибки интеграции со Stripe, которые приводят к сбоям

Доверие к перенаправлению: товар или услуга предоставляется после перехода на страницу успеха, прежде чем сервер получит проверенное состояние платежа.

Создание после каждого нажатия: вместо повторного использования хозяйственной операции с идемпотентностью система создает несколько Intents или Sessions.

Доверие к ценам от клиента: сервер принимает управляемые браузером сумму, валюту, скидку, налог, получателя или комиссию.

Неидемпотентное исполнение: при повторной доставке события система снова отгружает товар, предоставляет доступ или создает бухгалтерские записи.

Проверка лишь успешного случая: без внимания остаются аутентификация, отказы, обработка, превышение времени ожидания, отложенные способы оплаты, возвраты, оспаривания и выплаты.

Запуск без подготовки эксплуатации: отсутствуют сверка, оповещения, ответственный за исключения, инструменты поддержки, план возврата к предыдущей версии или репетиция реагирования на сбой.

Проверьте сбои, восстановление и сверку еще до запуска

Хороший план испытаний охватывает модель состояний, а не одну карту в штатном сценарии. Проверьте аутентификацию, нехватку средств, просроченные способы оплаты, промежуточные состояния, отложенный успех и отказ, сетевой обрыв после подтверждения, повторные команды, дубликаты и неупорядоченные веб-уведомления, частичное завершение списания, отмену, частичные и полные возвраты, оспаривания, неудачное продление подписки и неудачную выплату. Проверяйте и сообщение покупателю, и бухгалтерское состояние, а не только ответ HTTP.

Применяйте испытательный режим Stripe, документированные способы оплаты для проверки, Stripe CLI для местной пересылки веб-уведомлений и создания событий, а также испытательные часы для поддерживаемых сценариев выставления счетов. Проверяйте договор обработчика веб-уведомлений на версионированных наборах данных, но сохраняйте интеграционные испытания с испытательным API Stripe для предположений, которых не докажет имитация. Закрепляйте версии API и SDK и обновляйте их осознанно; до изменения рабочей системы проверяйте последствия для учетной записи, Connect, веб-уведомлений и мобильных приложений.

Для запуска подготовьте отдельные рабочие учетные данные и секреты конечных точек, доступ по принципу наименьших полномочий, MFA в панели управления, зарегистрированные домены, рабочие адреса возврата, наблюдение и проверенный путь поддержки. Начните с ограниченной группы пользователей или переключателя функции. Следите за долей завершенных покупок, отказами, аутентификацией, задержкой веб-уведомлений, ошибками обработки, расхождениями в исполнении, возвратами, оспариваниями, движением остатков и выплатами. Первые операции сверьте вручную от заказа покупателя через объект Stripe до расчета, а затем автоматизируйте сравнение и ведите очередь исключений с назначенным владельцем.

Создайте платежную систему, которую организация способна поддерживать

Настоящим результатом является не страница оформления заказа, а платежная система, которую совместно поддерживают специалисты по продукту, разработке, финансам, рискам и поддержке. Назначьте ответственных за изменения каталога и цен, учетные данные, обновления API, ошибки веб-уведомлений, расхождения сверки, возвраты, оспаривания, отрицательные остатки, выплаты и общение с покупателями. Предоставьте сотрудникам безопасные действия и журнал контроля, чтобы во время сбоя им не приходилось просить разработчиков вручную менять строки в базе.

Начните исследование с одного показательного движения средств и проследите его от начала до конца: предложение, налог, согласие, начало платежа, аутентификация, подтверждение, состояние заказа, исполнение, счет, возврат, оспаривание, остаток, выплата и запись в учете. Для каждого перехода определите полномочный источник, доказательство, границу идемпотентности, время ожидания, путь восстановления, владельца и показатель. Такое исследование выявляет отсутствующие правила до того, как они превратятся в код.

GARNO.TECH может спроектировать и реализовать Stripe Checkout или Elements, PaymentIntents, Billing, Connect, инфраструктуру веб-уведомлений, перенос данных, испытания, сверку, наблюдаемость и инструменты эксплуатации. Качественное сотрудничество оставляет команде документированные состояния и средства контроля, воспроизводимые испытания, наблюдение за асинхронными потоками и план запуска, финансовые результаты которого можно проверить. Именно такой должна быть платежная интеграция, достойная доверия покупателей.