Start With the Right Mental Model
Payments are eventually consistent distributed systems — not request/response APIs. Treat every call as potentially failing, every webhook as potentially duplicated, and every state as needing reconciliation.
The Five Rules
1. Idempotency keys on every write. Send a unique key per intent so retries don't double-charge.
2. Verify webhooks cryptographically. Always check the signature header — never trust the payload alone.
3. Persist state machines, not booleans. A payment is `pending → authorized → captured → settled` — track every transition.
4. Reconcile daily. Pull settlement reports and compare against your local ledger.
5. Sandbox like production. Use the same idempotency, webhook, and retry logic in dev as in prod.
Common Mistakes
Polling instead of webhooks. Storing card data (PCI scope explosion). Hardcoding currency to one value. Ignoring partial captures and refunds.
Payomatix's Approach
Our SDKs handle idempotency, webhook verification, and retry logic out of the box. You write business logic, not payment plumbing.