Android

A payment must never happen twice: reliability rules for an Android payments app

#Android #Kotlin #Payments #Reliability

A customer taps Pay. The spinner turns. The network drops for two seconds, the request times out, and the app says "Payment failed". The customer taps Pay again. Both payments go through.

Nothing in that story is exotic. The server did its job, the app did what it was told, and the customer lost money twice. The bug is not in a line of code, it is in a missing model of what "failed" means. Below are five rules that remove this class of bug from an Android payments app, and the tests that prove they hold.

Rule 1: the idempotency key is born before the request

Every payment gets a client-generated key (a UUID is enough) at the moment the payment is created, not at the moment it is sent. The key is saved together with the payment record, sent in a header with every attempt, and reused for every retry of that payment. A new payment gets a new key, always.

The server stores the key with the result. A second request with the same key does not create a second charge, it returns the first result. That turns "did my request arrive?" from a guess into a question the server can answer.

The classic mistake is generating the key inside the network call. Then every retry carries a fresh key, and the protection silently does nothing.

Rule 2: write and send are one transaction

If the app saves a payment and then sends it, there is a moment between the two where the process can die. If it sends and then saves, there is a moment where money moved and the app does not know. The fix is an outbox: in one Room transaction, write the payment row and an "outbox" row that says "this needs to be sent". A worker (WorkManager fits well, since it survives process death) drains the outbox, sends each entry with its key and marks it done only after the server answers.

Crash before the transaction commits: nothing happened, the user sees nothing. Crash after: the worker picks it up on the next start and sends it with the same key. Either way, there is no state where money moved and the app has no record of it.

Rule 3: a payment is a state machine, and "unknown" is a state

Most double charges come from an app that has only two outcomes: success and failure. Real life has a third: we sent it and do not know what happened. That state needs a name, its own UI and its own exit.

a lost answer is UNKNOWN, never FAILED
StateWhat the user seesWhat a retry does
CREATEDThe form, Pay button activeNothing to retry yet
SENDING"Processing", button disabledBlocked: one attempt in flight at a time
UNKNOWN"Checking the payment status"Asks the server for the status by key, never sends a new payment
CONFIRMEDReceiptNot allowed, terminal
DECLINEDThe bank's reason and a way to fix itNot allowed; trying again is a new payment with a new key
EXPIRED"The payment was not completed", support linkNot allowed, goes to reconciliation

Transitions live in one pure function: current state plus event gives the next state. No screen is allowed to set a state directly. That one function is also the easiest thing in the app to test.

Rule 4: partial failures need a question, not a retry

The dangerous answer from the network is no answer. These are the cases worth designing for, one by one:

Retries use exponential backoff with jitter, and are also triggered by the connectivity callback. But "the device has a network" is not "the backend is reachable", so connectivity only triggers an attempt, it never marks anything as sent.

Rule 5: money is an integer

Amounts are stored and passed as Long in minor units (cents, kopecks, tetri) with the currency code next to them. Never Double: 0.1 + 0.2 is not 0.3 in binary floating point, and a rounding error of one minor unit is still a wrong amount on a bank statement. Conversion to a human string happens once, at the UI edge, with the currency's own number of decimal places.

How to test it

Reliability rules are only real if a test breaks when they do. The minimum set:

And one thing tests cannot replace: reconciliation. Idempotency prevents duplicates the client can see. A daily comparison with the server's ledger catches the ones nobody saw.

What I'd do again, and the mistakes to avoid

What I would do again on any payments app: put the state machine and the outbox in place before the first screen, because retrofitting them means migrating payments that are already in flight. Make the payment flow injectable from day one (constructor injection with Dagger, Hilt or Koin), since every test above depends on swapping the network and the clock. And treat startup time as part of reliability: a payments app that opens slowly is one people force-close in the middle of a payment.

The mistakes to avoid: generating the idempotency key at send time; mapping a timeout to "failed"; letting UI code set payment states; retrying on a fixed timer; using floating point for money; and believing that idempotency alone ends double charges. The target is not exactly-once delivery, it is at-least-once delivery to a server that makes the second attempt harmless.

Платёж не должен пройти дважды: правила надёжности Android-приложения для платежей

#Android #Kotlin #Payments #Reliability

Клиент нажимает «Оплатить». Крутится индикатор. Сеть пропадает на две секунды, запрос падает по таймауту, и приложение пишет «Платёж не прошёл». Клиент нажимает «Оплатить» ещё раз. Проходят оба платежа.

В этой истории нет ничего экзотического. Сервер сделал свою работу, приложение сделало то, что ему сказали, а клиент заплатил дважды. Баг не в строке кода, а в отсутствии модели того, что вообще значит «не прошёл». Ниже — пять правил, которые убирают этот класс багов из Android-приложения для платежей, и тесты, которые доказывают, что правила держатся.

Правило 1: ключ идемпотентности рождается до запроса

Каждый платёж получает ключ, сгенерированный на клиенте (UUID достаточно), в момент создания платежа, а не в момент отправки. Ключ сохраняется вместе с записью о платеже, уходит в заголовке с каждой попыткой и переиспользуется для каждого повтора этого платежа. Новый платёж — всегда новый ключ.

Сервер хранит ключ вместе с результатом. Второй запрос с тем же ключом не создаёт второе списание, а возвращает первый результат. Так вопрос «дошёл ли мой запрос?» превращается из догадки в вопрос, на который сервер может ответить.

Классическая ошибка — генерировать ключ внутри сетевого вызова. Тогда каждый повтор несёт новый ключ, и защита молча ничего не делает.

Правило 2: запись и отправка — одна транзакция

Если приложение сначала сохраняет платёж, а потом отправляет, между этими шагами есть момент, когда процесс может умереть. Если сначала отправляет, а потом сохраняет, есть момент, когда деньги ушли, а приложение об этом не знает. Решение — outbox: в одной транзакции Room записываются строка платежа и строка в «исходящие», которая говорит «это нужно отправить». Воркер (WorkManager хорошо подходит, потому что переживает смерть процесса) разбирает исходящие, отправляет каждую запись с её ключом и помечает выполненной только после ответа сервера.

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

Правило 3: платёж — это конечный автомат, и «неизвестно» — это состояние

Большинство двойных списаний происходят в приложениях, где у платежа только два исхода: успех и ошибка. В жизни есть третий: мы отправили и не знаем, что случилось. У этого состояния должно быть имя, свой UI и свой выход.

потерянный ответ — это UNKNOWN, а не FAILED
СостояниеЧто видит пользовательЧто делает повтор
CREATEDФорма, кнопка «Оплатить» активнаПовторять пока нечего
SENDING«Обрабатываем», кнопка заблокированаЗапрещён: в полёте только одна попытка
UNKNOWN«Проверяем статус платежа»Запрашивает у сервера статус по ключу, никогда не отправляет новый платёж
CONFIRMEDЧекЗапрещён, финальное состояние
DECLINEDПричина от банка и способ её исправитьЗапрещён; новая попытка — это новый платёж с новым ключом
EXPIRED«Платёж не завершён», ссылка на поддержкуЗапрещён, уходит на сверку

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

Правило 4: частичный сбой требует вопроса, а не повтора

Самый опасный ответ сети — отсутствие ответа. Вот случаи, под которые стоит проектировать по одному:

Повторы идут с экспоненциальной задержкой и джиттером, а ещё запускаются по колбэку подключения к сети. Но «у устройства есть сеть» — не то же самое, что «бэкенд доступен», поэтому подключение только запускает попытку и никогда не помечает платёж отправленным.

Правило 5: деньги — это целое число

Суммы хранятся и передаются как Long в минимальных единицах (центы, копейки, тетри) с кодом валюты рядом. Никогда не Double: в двоичной плавающей точке 0.1 + 0.2 не равно 0.3, а ошибка округления в одну копейку — всё равно неверная сумма в банковской выписке. Перевод в строку для человека происходит один раз, на границе UI, с тем числом знаков после запятой, которое положено валюте.

Как это тестировать

Правила надёжности реальны, только если при их нарушении падает тест. Минимальный набор:

И одну вещь тесты не заменят: сверку. Идемпотентность предотвращает дубли, которые видит клиент. Ежедневное сравнение с журналом операций на сервере ловит те, которых не видел никто.

Что я сделал бы снова и каких ошибок избегать

Что я бы повторил в любом платёжном приложении: ставить автомат состояний и outbox до первого экрана, потому что встраивать их потом — значит мигрировать платежи, которые уже в полёте. С первого дня делать платёжный поток внедряемым (инъекция через конструктор с Dagger, Hilt или Koin): каждый тест выше зависит от подмены сети и часов. И считать время запуска частью надёжности: платёжное приложение, которое долго открывается, люди закрывают силой посреди платежа.

Ошибки, которых стоит избегать: генерировать ключ идемпотентности в момент отправки; превращать таймаут в «ошибку»; позволять UI-коду выставлять состояния платежа; повторять по фиксированному таймеру; использовать плавающую точку для денег; и верить, что одна идемпотентность покончит с двойными списаниями. Цель — не доставка ровно один раз, а доставка хотя бы один раз на сервер, для которого вторая попытка безвредна.

— Dmitry