Providers retry. Queues retry. People double-click. If each delivery creates a row, one payment becomes two receipts, or one booking becomes two.
QR Ph payments and digital payments for online stores already say the order update should be webhook-driven, verified, and idempotent. They stop at the word. This is the mechanism. It is not a wallet setup guide.
Queues will run a job more than once. That is normal. The side effect still has to happen once.
The pattern
The caller sends a key for that operation. Stripe’s Idempotency-Key header is the well-known version: the same key returns the stored result instead of performing the operation again.
We store the key with the result. A unique constraint on the key is what makes the second delivery lose. Code that checks and then inserts, without the constraint, still races.
- Verify the caller. A signature check comes before any of this. Idempotency does not authenticate anyone.
- If the key already has a stored result, return it.
- Otherwise do the work in a transaction and store the key with that result.
- If the unique insert loses, read the winner’s result and return that.
The key is per operation, not per customer and not per day. Reusing one key for two different payments is a bug in the client.
What this is not
It is not a reason to add a service. A column and a unique index on the existing app is the usual fix. It does not replace the payment articles. Those still cover how GCash, Maya, and QR Ph should update an order. This covers why the second delivery must not create a second one.
Straight next step
If a retry has already created duplicate bookings, receipts, or stock movements, send one example pair. We will put the key on that operation before we talk about a new integration.
