Technology handbook
Payment gateway integration
Checkout, webhooks, idempotency, refunds, subscriptions, reconciliation and compliance.
- Topics
- 24
- Sections
- 4
Payment flow
Hosted checkout
Redirect to the gateway's page so card data never reaches your server.
- The browser leaves for the gateway's page, so card data never touches your server.
- Keeping card data out is what keeps your compliance scope small.
- Branding and flow control are limited to what the gateway exposes.
Payment intents
Model a payment as an object that moves through explicit states.
- A payment is an object moving through explicit, inspectable states.
- State on the gateway is the truth; your record is a mirror of it.
- A state your code does not handle stalls the order silently.
Client-side elements
Embed gateway-hosted fields while keeping your own layout.
- Gateway-hosted fields embed inside your own layout.
- The sensitive input lives in the gateway's frame, not in your DOM.
- Styling is constrained, because you cannot reach inside that frame.
Authentication and 3-D Secure
Handle the extra verification step regulations may require.
- An extra verification step is handled where regulation requires it.
- The flow can interrupt at any point, so the code path is not linear.
- Treating a challenge as a failure loses payments that would have succeeded.
Currencies and amounts
Store amounts in minor units and avoid floating point entirely.
- Amounts are stored in minor units, never as floating point.
- Floating point makes a total that is a fraction of a cent wrong.
- Currencies differ in how many minor units they have, so the divisor is not always a hundred.
Payment methods
Support cards, wallets and local methods per market.
- Cards, wallets and local methods are supported per market.
- The method a market expects is often not a card at all.
- Each method has its own settlement time and its own refund rules.
Correctness
Idempotency keys
Send a key so a retried create cannot charge twice.
- A key makes a retried create safe rather than a second charge.
- Network failure after a request is indistinguishable from failure before it.
- The key must be derived from the attempt, not generated per retry.
Webhook fulfilment
Treat the webhook as the authoritative completion signal.
- The webhook is the authoritative signal that the payment completed.
- A browser redirect can be closed, blocked or forged; the webhook cannot.
- Fulfilling on redirect alone loses orders whenever the user closes the tab.
Signature verification
Verify every webhook before acting on it.
- Every webhook is verified before anything acts on it.
- An unverified endpoint is one anyone on the internet may post to.
- Verification uses the raw body, so parsing before checking breaks it.
Duplicate event handling
Make fulfilment safe to run more than once.
- Fulfilment is safe to run more than once.
- Delivery is at least once, so a repeat is expected, not exceptional.
- Keying on the event id is what makes the repeat a no-op.
Order state machine
Model pending, paid, failed and refunded as explicit states.
- Pending, paid, failed and refunded are modelled as explicit states.
- Explicit states are what make an inconsistent order visible.
- A transition the machine does not allow is a bug caught rather than applied.
Race conditions
Handle a webhook arriving before your own record is written.
- A webhook can arrive before your own record has been written.
- The gateway does not wait for your database to commit.
- Creating the record on demand from the webhook is what survives the race.
Lifecycle operations
Refunds
Issue full and partial refunds and reflect them in your records.
- Full and partial refunds are issued and reflected in your own records.
- A refund on the gateway that your ledger does not know about is a discrepancy.
- Refunding more than was captured is refused, so partials must be tracked.
Disputes and chargebacks
Respond to a dispute and account for the reversal.
- A dispute is answered and the reversal accounted for.
- The money is taken back immediately, before the dispute is decided.
- Evidence must be submitted inside a window that is short and fixed.
Subscriptions
Model recurring billing, trials, upgrades and proration.
- Recurring billing, trials, upgrades and proration are modelled.
- Proration is what makes a mid-cycle change charge the right amount.
- A plan change alters future invoices, not the one already issued.
Failed payments and dunning
Retry a failed renewal and communicate before cancelling.
- A failed renewal is retried and communicated before access ends.
- Most renewal failures are temporary and succeed on a later attempt.
- Cancelling on the first failure loses customers who would have paid.
Invoices and receipts
Produce documents that match what was actually charged.
- Documents match what was actually charged.
- A receipt that disagrees with the charge is a support case and a compliance risk.
- An issued invoice is a record, so a correction is a credit note rather than an edit.
Cancellation
End a subscription at the right moment for billing and access.
- A subscription ends at the right moment for both billing and access.
- Ending access immediately on a paid period is a refund the customer did not get.
- Cancel-at-period-end and cancel-now are different promises.
Operating & compliance
Reconciliation
Compare gateway settlement against your own ledger regularly.
- Gateway settlement is compared against your own ledger regularly.
- Fees, refunds and disputes mean the payout never equals the order total.
- A discrepancy found monthly is cheaper than one found at audit.
Test mode and fixtures
Exercise success, failure and dispute paths before going live.
- Success, failure and dispute paths are exercised before going live.
- Only the failure paths reveal whether the state machine is complete.
- Test mode has its own keys and its own data, entirely separate from live.
Key management
Separate publishable and secret keys and rotate them safely.
- Publishable and secret keys are separated and rotated safely.
- A secret key in the client bundle is a full compromise of the account.
- Rotation needs both keys valid briefly, or the swap causes an outage.
PCI scope
Keep card data out of your systems so scope stays minimal.
- Card data is kept out of your systems so scope stays minimal.
- Scope is decided by what touches card data, not by what stores it.
- Logging a full card number pulls your logs into scope.
Taxes and regional rules
Apply the tax and disclosure rules a market requires.
- Each market's tax and disclosure rules are applied.
- Tax depends on where the customer is, not where the business is.
- Displaying a price without the required tax treatment is a legal problem.
Audit logging
Record who changed a price, a refund or a subscription, and when.
- Who changed a price, a refund or a subscription is recorded, and when.
- Money changes need attribution, because they will eventually be questioned.
- A log the application can edit is not evidence of anything.
Sources
- Payment gateway integration official documentation