A payment must never happen twice: reliability rules for an Android payments app
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.
| State | What the user sees | What a retry does |
|---|---|---|
| CREATED | The form, Pay button active | Nothing to retry yet |
| SENDING | "Processing", button disabled | Blocked: 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 |
| CONFIRMED | Receipt | Not allowed, terminal |
| DECLINED | The bank's reason and a way to fix it | Not allowed; trying again is a new payment with a new key |
| EXPIRED | "The payment was not completed", support link | Not 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:
- the request never left the device: safe to send again with the same key;
- the server accepted it, the response was lost: ask for the status by key;
- the app was killed after a success, before saving it: the outbox resends, the key returns the stored result;
- the user taps Pay again on a frozen screen: the state machine blocks it while SENDING or UNKNOWN;
- a push about the payment arrives before the HTTP response: it is just another event for the state machine, not a second source of truth.
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:
- the state machine as a table: every state times every event, with the expected next state or "rejected";
- a fake server that accepts the payment and then drops the response: the app must end in CONFIRMED after a status check, with exactly one charge on the fake;
- process death between the transaction and the send: after restart, exactly one request with the original key;
- the same key replayed three times: one charge, three identical answers;
- amount round-trips: from input string to minor units to the UI and back, with currencies that have zero and three decimal places.
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-приложения для платежей, и тесты, которые доказывают, что правила держатся.
Правило 1: ключ идемпотентности рождается до запроса
Каждый платёж получает ключ, сгенерированный на клиенте (UUID достаточно), в момент создания платежа, а не в момент отправки. Ключ сохраняется вместе с записью о платеже, уходит в заголовке с каждой попыткой и переиспользуется для каждого повтора этого платежа. Новый платёж — всегда новый ключ.
Сервер хранит ключ вместе с результатом. Второй запрос с тем же ключом не создаёт второе списание, а возвращает первый результат. Так вопрос «дошёл ли мой запрос?» превращается из догадки в вопрос, на который сервер может ответить.
Классическая ошибка — генерировать ключ внутри сетевого вызова. Тогда каждый повтор несёт новый ключ, и защита молча ничего не делает.
Правило 2: запись и отправка — одна транзакция
Если приложение сначала сохраняет платёж, а потом отправляет, между этими шагами есть момент, когда процесс может умереть. Если сначала отправляет, а потом сохраняет, есть момент, когда деньги ушли, а приложение об этом не знает. Решение — outbox: в одной транзакции Room записываются строка платежа и строка в «исходящие», которая говорит «это нужно отправить». Воркер (WorkManager хорошо подходит, потому что переживает смерть процесса) разбирает исходящие, отправляет каждую запись с её ключом и помечает выполненной только после ответа сервера.
Краш до коммита транзакции — ничего не произошло, пользователь ничего не видит. Краш после — воркер подхватит запись при следующем запуске и отправит с тем же ключом. В любом случае не бывает состояния, в котором деньги ушли, а у приложения нет о них записи.
Правило 3: платёж — это конечный автомат, и «неизвестно» — это состояние
Большинство двойных списаний происходят в приложениях, где у платежа только два исхода: успех и ошибка. В жизни есть третий: мы отправили и не знаем, что случилось. У этого состояния должно быть имя, свой UI и свой выход.
| Состояние | Что видит пользователь | Что делает повтор |
|---|---|---|
| CREATED | Форма, кнопка «Оплатить» активна | Повторять пока нечего |
| SENDING | «Обрабатываем», кнопка заблокирована | Запрещён: в полёте только одна попытка |
| UNKNOWN | «Проверяем статус платежа» | Запрашивает у сервера статус по ключу, никогда не отправляет новый платёж |
| CONFIRMED | Чек | Запрещён, финальное состояние |
| DECLINED | Причина от банка и способ её исправить | Запрещён; новая попытка — это новый платёж с новым ключом |
| EXPIRED | «Платёж не завершён», ссылка на поддержку | Запрещён, уходит на сверку |
Переходы живут в одной чистой функции: текущее состояние плюс событие дают следующее состояние. Ни одному экрану не разрешено выставлять состояние напрямую. Эта функция заодно — самое простое для тестирования место во всём приложении.
Правило 4: частичный сбой требует вопроса, а не повтора
Самый опасный ответ сети — отсутствие ответа. Вот случаи, под которые стоит проектировать по одному:
- запрос не покинул устройство: можно безопасно отправить снова с тем же ключом;
- сервер принял запрос, ответ потерялся: спросить статус по ключу;
- приложение убили после успеха, но до сохранения: outbox отправит повторно, а ключ вернёт сохранённый результат;
- пользователь снова жмёт «Оплатить» на зависшем экране: автомат блокирует это в SENDING и UNKNOWN;
- пуш о платеже пришёл раньше HTTP-ответа: это просто ещё одно событие для автомата, а не второй источник правды.
Повторы идут с экспоненциальной задержкой и джиттером, а ещё запускаются по колбэку подключения к сети. Но «у устройства есть сеть» — не то же самое, что «бэкенд доступен», поэтому подключение только запускает попытку и никогда не помечает платёж отправленным.
Правило 5: деньги — это целое число
Суммы хранятся и передаются как Long в минимальных единицах (центы, копейки, тетри) с кодом валюты рядом. Никогда не Double: в двоичной плавающей точке 0.1 + 0.2 не равно 0.3, а ошибка округления в одну копейку — всё равно неверная сумма в банковской выписке. Перевод в строку для человека происходит один раз, на границе UI, с тем числом знаков после запятой, которое положено валюте.
Как это тестировать
Правила надёжности реальны, только если при их нарушении падает тест. Минимальный набор:
- автомат состояний как таблица: каждое состояние на каждое событие, с ожидаемым следующим состоянием или «отклонено»;
- фейковый сервер, который принимает платёж и теряет ответ: после проверки статуса приложение должно оказаться в CONFIRMED, а на фейке — ровно одно списание;
- смерть процесса между транзакцией и отправкой: после перезапуска — ровно один запрос с исходным ключом;
- один и тот же ключ трижды: одно списание и три одинаковых ответа;
- путь суммы туда и обратно: от введённой строки к минимальным единицам, в UI и обратно, на валютах с нулём и тремя знаками после запятой.
И одну вещь тесты не заменят: сверку. Идемпотентность предотвращает дубли, которые видит клиент. Ежедневное сравнение с журналом операций на сервере ловит те, которых не видел никто.
Что я сделал бы снова и каких ошибок избегать
Что я бы повторил в любом платёжном приложении: ставить автомат состояний и outbox до первого экрана, потому что встраивать их потом — значит мигрировать платежи, которые уже в полёте. С первого дня делать платёжный поток внедряемым (инъекция через конструктор с Dagger, Hilt или Koin): каждый тест выше зависит от подмены сети и часов. И считать время запуска частью надёжности: платёжное приложение, которое долго открывается, люди закрывают силой посреди платежа.
Ошибки, которых стоит избегать: генерировать ключ идемпотентности в момент отправки; превращать таймаут в «ошибку»; позволять UI-коду выставлять состояния платежа; повторять по фиксированному таймеру; использовать плавающую точку для денег; и верить, что одна идемпотентность покончит с двойными списаниями. Цель — не доставка ровно один раз, а доставка хотя бы один раз на сервер, для которого вторая попытка безвредна.
— Dmitry