API за плащания: повторни заявки без двойно изпълнение

Дайте идентичност на бизнес операцията

Поръчката има собствен идентификатор, а всеки платежен опит има отделна идентичност. Ключът за повторение трябва да описва конкретното действие, не произволното време на HTTP заявката. Ако при всяко повторение създавате нов ключ, системата може да възприеме същото действие като ново плащане.

Пример е покупка на пакет кредити. Клиентът натиска два пъти, защото първият отговор се бави. Сървърът трябва да върне съществуващия резултат или чакащо състояние за същата операция, а не да създава два отделни зареждащи платежни опита.

Инструменти за разработчици

Обвържете ключа с данните

Един и същ ключ не трябва да позволява различна сума, валута или поръчка. Запишете безопасно представяне на параметрите и сравнявайте повторните заявки с оригиналната. При несъответствие върнете ясна грешка, вместо да изпълните промененото действие под стар идентификатор.

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

Оркестрация на плащания

Различавайте отказ и неизвестен резултат

Отказът предполага потвърден отговор, който може да се класифицира като окончателен. Таймаут след изпращане не доказва, че доставчикът не е създал плащане. Отбележете неизвестния резултат като чакащ за изясняване и запазете необходимите референции за последваща проверка.

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

Управлявайте едновременните заявки

Две копия на една заявка могат да пристигнат почти едновременно. Проверка в паметта на един процес не е достатъчна при няколко инстанции. Използвайте подходяща устойчива защита на сървъра, която гарантира, че само едно изпълнение създава външната операция.

Пазете резултата така, че повторението да получи същия смислен отговор. Ако процесът прекъсне, трябва да има възстановим статус. Не оставяйте неопределен запис без отговорник и без начин да се сравни с операцията при доставчика.

Завършвайте чрез проверен резултат

Webhook или заявка за статус може да довърши първоначално неизвестния резултат. Проверявайте достоверността и връзката с правилната поръчка. Повторението на известието не трябва да добавя втори път кредити, да изпраща втори продукт или да създава ново счетоводно действие.

Поддържайте история на преходите и контролирайте разрешените промени. Не заменяйте по-ново окончателно състояние с остаряла информация само защото е пристигнала последна по мрежата. При противоречие оставете ясна причина за оперативен преглед.

Направете договора видим за интегратора

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

Прегледайте актуалния OrsunPay API и реалните възможности на конектора. Не приемайте, че функцията на доставчика се наследява автоматично от всеки слой. Преди запуск проверете паралелно повторение, прекъсване след изпращане и закъсняло потвърждение, като сравните броя действително създадени платежни операции.

Източници

• Stripe: idempotent requests
• Stripe Webhooks