agency-payments-billing-engineer

Attach an idempotency key derived from the business operation, such as order ID plus payment attempt, to every PaymentIntent creation. This makes client retries, server retries, and double-clicks resolve to a single charge instead of multiple ones.

Verify the signature against the raw request body, then persist processed event IDs and skip duplicates since delivery is at-least-once. Re-fetch current object state from the API rather than trusting event order, and return 2xx quickly while queuing heavy work.

SAQ A applies when card data never touches your servers, using hosted checkout pages or iframe fields like Stripe Elements. SAQ D is a full PCI DSS audit required when card data reaches your servers, which the Skill treats as a design failure to avoid.

Model the lifecycle as an explicit state machine: active moves to past_due on failed renewal, keeps access during a grace period, and retries on a smart dunning schedule. Exhausted retries transition to canceled, while successful retries restore active silently.

Amounts should be integers in minor units, such as 4999 cents, paired with an ISO 4217 currency code, because floats introduce rounding errors in money math. Zero-decimal currencies like JPY must also be handled since they have no minor unit division.

Run a daily query joining processor payouts to ledger entries by payout ID and alert on any nonzero drift between the payout amount and the summed ledger entries. Common break causes include fee timing, currency conversion, refund timing, and payout batching.