Подключение платежей Stripe: архитектура, надежность и запуск

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

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

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

Начните с движения денег, а не с платежной формы

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

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

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

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

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

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

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

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

Встройте Stripe в систему достоверного финансового учета

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

Создайте внутреннюю запись платежа с собственным устойчивым идентификатором и свяжите ее с соответствующими объектами Stripe Customer, Checkout Session, PaymentIntent, Invoice, Subscription, Charge, Refund, Transfer или подключенной учетной записью. Храните идентификаторы и значимые состояния, а не копии чувствительных данных. Ведите журнал команд, проверенных событий, переходов состояния и бухгалтерских последствий. Тогда у служб поддержки и финансов будет последовательная история, которая не исчезает вместе с сеансом браузера и выдерживает повторные обращения к API.

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

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

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

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

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

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

• Фоновые исполнители и операционная команда: выполняют заказы, отправляют оповещения, повторяют операции и сверяют записи, следя за очередями исключений с назначенными ответственными.

Используйте PaymentIntents как автомат состояний платежа

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

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

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

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

— GARNO.TECH Engineering

Выбирайте Checkout или Elements по границам ответственности, а не по внешнему виду

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

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

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

Сделайте сообщения о событиях надежными, проверенными и защищенными от повторов

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

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

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

Перечень мер безопасности на всей границе платежной системы

• Храните секретные ключи только на сервере в управляемом хранилище секретов; ограничивайте доступ, меняйте ключ при раскрытии и никогда не добавляйте учетные данные в хранилище кода.

• Вычисляйте сумму, валюту, скидки, налог, получателя и комиссии по доверенным серверным данным; проверяйте право клиента действовать с указанным заказом.

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

• Защищайте от повторного выполнения команды Stripe и внутренние переходы состояния; требуйте уникальности идентификаторов событий и финансовых ссылок.

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

• Требуйте многофакторную аутентификацию и минимальные права для Dashboard и инструментов поддержки; пересматривайте доступ и дополнительно защищайте возвраты и выплаты с серьезными последствиями.

• Записывайте внутренние идентификаторы связи и запросов Stripe, переходы состояния и исполнителей, но не данные карт, клиентские секреты, персональные сведения или исходные чувствительные данные.

Моделируйте подписки и торговые площадки как финансовые операции

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

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

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

Шесть ошибок, из-за которых платежи превращаются в происшествия

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

• Создание после каждого нажатия: появление нескольких Intent или Session вместо повторного использования той же хозяйственной операции с защитой от повторов.

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

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

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

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

До запуска проверьте отказы, восстановление и финансовую сверку

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

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

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

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

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

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

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