Verifying Payments Safely

The golden rule of payment security: the client can lie. A success page, a query parameter, a JavaScript callback — all can be forged or replayed by a determined user.

Access and fulfilment must be decided by signals you can cryptographically trust, originating from the provider's servers, never from the user's browser.

Webhooks arrive at a public URL, so anyone could POST fake events to it. Providers sign each webhook with a secret only you and they know.

Always verify the signature before trusting the payload. An unsigned or mis-signed request must be rejected outright — this single check blocks the most common payment exploit.

Even a genuine, signed event must be checked against your expectations. Confirm the amount and currency match what the order should have cost.

If a $9 order reports a $0.50 payment, reject it. Signature proves the message is from the provider; amount-checking proves the customer paid what they owe.

Providers deliver webhooks at least once, meaning duplicates are normal. If your handler grants credits or extends a subscription, processing the same event twice causes real harm.

Record each event ID you have processed and skip repeats. Make your handler safe to run any number of times for the same event.

Verification means matching the provider's record to your own. Pull the authoritative object — the payment intent or subscription — and compare its status to what you expect before acting.

Re-fetching from the provider's API inside the handler closes the gap between a possibly stale event and current reality.

Providers expect a quick 2xx response or they retry, causing duplicate deliveries. Acknowledge receipt promptly, then do heavy work asynchronously.

The pattern: verify the signature, enqueue the event, return 200. A background worker performs fulfilment. This keeps the endpoint reliable under load and during slow operations.

API keys, webhook secrets, and signing keys are credentials. Hard-coding them in source or shipping them to the client is a breach waiting to happen.

Store them in environment variables or a secrets manager. The secret key must live only on your server; the client gets the publishable key, which is safe to expose.

Money flows backward too. A refund or a chargeback dispute should revoke access or adjust entitlements, driven by webhook events like charge.refunded and charge.dispute.created.

If you only handle the payment and ignore the reversal, a refunded customer keeps paid features for free. Wire the backward events as carefully as the forward ones.

When money is involved, you need an immutable trail. Log every webhook received, every fulfilment decision, and every entitlement change with timestamps and IDs.

This audit log is your defense in a dispute and your fastest debugging tool when a customer says "I paid but have no access". Never log raw card data, only references.

When verification fails — bad signature, mismatched amount, unknown order — the safe default is to deny access and alert yourself, not to grant the benefit of the doubt.

A payment system should fail closed. A false negative annoys one customer you can fix manually; a false positive gives away your product or invites fraud.

Before going live, confirm the chain: signature verified, amount and currency matched, event idempotently processed, provider object reconciled, secrets in env, refunds handled, and failures fail closed.

Ask your AI assistant to audit the integration against this list. Each item that is missing is a door an attacker or a bug can walk through.

Confirm the first thing every webhook handler must do.

Safe verification means trusting only the provider's signed server-side signals. Verify every webhook's signature, then check the amount and currency, process events idempotently, and reconcile against the live provider object before granting access.

Keep secrets in environment variables, respond fast and process asynchronously, handle refunds and disputes by revoking access, log an audit trail, and always fail closed. Run the full checklist before going live.