Платіжний API: як обробляти тайм-аути та повторні запити

Почніть з ідентифікатора бізнесової дії

Один номер замовлення може мати кілька платіжних спроб, але кожна спроба повинна мати зрозумілу причину створення. Перед першим викликом запишіть намір оплатити конкретну суму в конкретній валюті. Повтор через втрату відповіді стосується того самого наміру; нова покупка або погоджена зміна суми є іншою бізнесовою дією.

Наприклад, клієнт натиснув оплату двічі через повільне з’єднання. Сервер повинен розпізнати повтор, а не створити два незалежні замовлення. Якщо клієнт пізніше змінив склад покупки, повторне використання старої спроби теж може бути помилкою. Тому ключ повторюваності пов’язують із незмінними параметрами операції та її життєвим циклом, а не лише з користувачем або поточним часом.

Інструменти розробника

Узгодьте можливості конкретного API

Різні платіжні інтерфейси мають різні правила повторних запитів, ключів і строків зберігання результату. Документація Stripe PaymentIntents описує власний об’єкт платіжного процесу; це не гарантія ідентичної поведінки будь-якого конектора. Перевіряйте контракт того API, яке фактично викликає ваш сервер, і не переносіть назви заголовків між сервісами без підтвердження.

OrsunPay надає програмний шар оркестрації для власних акаунтів мерчанта у провайдерів. Його API та прямий API провайдера є різними межами відповідальності. У схемі інтеграції позначте, хто зберігає ідентифікатор операції, хто перевіряє повтор і хто повертає поточний статус. Якщо частина функцій недоступна, потрібно спроєктувати явну серверну поведінку, а не сподіватися на приховану автоматизацію.

Кабінет мерчанта

Розрізняйте відмову та невідомий результат

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

Покупцю потрібне чесне повідомлення про перевірку, а підтримці — номер замовлення та безпечні технічні дані. Не показуйте необроблені відповіді провайдера з внутрішніми подробицями. Встановіть операційний строк, після якого випадок переходить до ручного розгляду, і опишіть, хто перевіряє результат у провайдера. Цей строк є правилом вашого процесу, а не вигаданою гарантією часу виконання платежу.

Приймайте серверні події незалежно від відповіді

Вебхук може надійти після тайм-ауту або раніше, ніж завершиться синхронний запит. Обидва канали повинні працювати з одним записом спроби та однаковими правилами зміни стану. Перевіряйте підпис, акаунт, суму й валюту перед тим, як позначити замовлення оплаченим. Дубльована подія не повинна повторно запускати виконання.

Розділіть платіжний результат і подальшу бізнесову дію. Якщо генерація документа зупинилася, повторіть її для вже оплаченого замовлення, а не весь платіжний запит. У журналі має бути видно, яка саме дія не завершилася. Це дозволяє відновлювати роботу без подвійних списань і без неправдивого повідомлення покупцю про фінансову помилку.

Перевірте конкурентні запити

Тестування одного запиту не показує проблем паралельної обробки. Два серверні процеси можуть одночасно прочитати стан і спробувати виконати ту саму зміну. Використовуйте обмеження та атомарні переходи в сховищі, які відповідають вашій архітектурі. Конкретний механізм залежить від бази даних, але результат повинен залишатися однаковим при повторенні сценарію.

• Надішліть два запити для одного незмінного наміру одночасно.
• Перервіть з’єднання після прийняття операції зовнішнім сервісом.
• Отримайте вебхук до завершення синхронної відповіді.
• Повторіть виконання замовлення після збою допоміжного сервісу.

Підготуйте звірку без здогадок

Зберігайте зв’язки між замовленням, внутрішньою спробою та ідентифікатором провайдера. Операційний перегляд повинен дозволяти знайти всі спроби одного замовлення та зрозуміти, яка стала успішною. Не видаляйте невдалі спроби лише заради охайного інтерфейсу: вони пояснюють причини повторів і звернень до підтримки.

У щоденному контролі окремо переглядайте невідомі результати й довго незавершені операції. OrsunPay не слід описувати як автоматичний каскад між провайдерами або маршрутизацію за вартістю без підтвердженої реалізації. Спочатку забезпечте передбачувану поведінку однієї інтеграції, а потім розширюйте її. Власні договори провайдерів і окрема програмна плата залишаються частиною цієї архітектури.

Джерела

• Stripe — Об’єкти PaymentIntent
• Stripe — Вебхуки