The short answer: specify the money outcome, not just checkout
Payment gateway integration requirements should define the commercial model, checkout ownership, payment and order states, identifiers, authentication, idempotency, webhooks, fulfilment gates, refunds, disputes, reconciliation, permissions, monitoring, and launch evidence. A successful API response is not enough: the customer, product, gateway, finance records, and fulfilment process must agree about what happened.
Start with one complete journey—for example, a customer pays for a confirmed booking and later receives a partial refund. Name the system of record, every external and internal identifier, the evidence that permits fulfilment, and the owner of any mismatch. Then choose the gateway and integration pattern that can support that contract.
This guide narrows the broader API integration requirements checklist to money movement. For recurring product access, also use the SaaS subscription billing requirements guide.
If the unresolved question is whether checkout should stay on a managed platform, move behind a headless storefront, or become part of a wider custom system, use the Shopify vs custom ecommerce decision guide to define that ownership boundary before designing the payment integration.
Define the commercial and system boundary first
“Take payments” hides several product decisions. Record who is paying whom, what is being purchased, when the amount becomes final, supported countries and currencies, tax ownership, payment methods, whether authorization and capture are separate, refund policy, dispute handling, and which team owns customer support and reconciliation.
Then draw the system boundary: browser or mobile client, application backend, gateway, order or booking service, inventory or entitlement service, finance ledger, messaging, analytics, and support tools. For each boundary, state which identifiers cross it and which system owns amount, currency, customer, order, payment, refund, and settlement truth.
| Decision | Requirement | Evidence |
|---|---|---|
| Checkout surface | Hosted, embedded, or app-native ownership is explicit | Approved architecture and scope review |
| Fulfilment gate | Named verified state permits one business action | Server-side event plus idempotent result |
| Financial truth | Orders, payments, refunds, fees, and payouts can be compared | Transaction-level reconciliation report |
Checkout choice changes security and compliance responsibility. The PCI Security Standards Council payment-page guidance focuses on authorization, integrity, and change detection for scripts and security-impacting headers. Treat compliance scope as a specialist-reviewed architecture input, not a label copied from a provider page.
Write a payment-to-business state contract
Gateways expose states such as requires action, authorized, pending, captured, refused, cancelled, refunded, or disputed. Your product may instead use awaiting payment, confirmed, fulfilled, refund requested, or closed. Never collapse the two vocabularies into a single “paid” Boolean.
For every provider event, record the current and next business state, permitted side effect, customer-facing message, retriable behavior, support action, and evidence retained. The Stripe PaymentIntent reference explicitly models a payment across multiple statuses, while the Adyen integration checklist calls out pending results, webhooks, modifications, reporting, and reconciliation. The exact names vary, but the need for a lifecycle contract does not.
Make retries safe at both boundaries
A customer can tap twice, the network can fail after the gateway accepted a request, and a webhook can be delivered more than once. Give each business operation a stable key, reuse it only for the same intent, and enforce uniqueness where the business side effect is recorded. Provider idempotency is useful but does not replace local order and fulfilment constraints. Stripe documents idempotency keys as a way to repeat a request safely after connection failure.
Connect checkout, fulfilment, and customer communication
Define amount calculation, currency precision, tax and discount inputs, inventory or slot reservation, authentication or redirect behavior, cancellation, resumption after app or browser interruption, and what the customer sees while the result is unknown. Do not show a final confirmation before the system has the evidence required by the fulfilment rule.
Webhooks should be verified using the provider contract, accepted quickly, recorded durably, deduplicated, and processed asynchronously where appropriate. The return page can explain progress, but it should not be the only mechanism that changes an order or grants access. Link the provider event, payment, order, fulfilment action, and notification so support can trace one customer case end to end.
Write customer messages for approved, declined, pending, abandoned, duplicated, cancelled, and refunded outcomes. Avoid exposing provider error codes or claiming money moved before it did. Say what the customer can safely do next and whether a retry could create a second attempt.
Design refunds, reconciliation, and operator recovery
Refunds need their own state machine: requested, submitted, pending, succeeded, failed, or cancelled where supported. Define full and partial amounts, cumulative limits, reason capture, approval permissions, customer notification, order or booking consequences, and accounting treatment. A provider accepting a refund request is not always proof that the customer has received the money.
Reconciliation should compare independent records at transaction level. Find paid gateway transactions without confirmed orders, fulfilled orders without settled payment evidence, amount or currency mismatches, duplicate captures, unreflected refunds, and payout or fee differences. Assign every exception a state, owner, resolution action, and audit trail.
Operator tools should expose masked, minimum-necessary data; current and historical state; linked identifiers; webhook and API attempts; permitted next actions; and the reason for every manual change. Separate view, refund, retry, and configuration privileges. Require stronger approval for costly or irreversible actions.
Break the payment journey before approving launch
Run the provider's supported sandbox scenarios, but test the product outcome too. For each case, verify the customer message, provider state, local payment state, order or entitlement, fulfilment, notification, support view, logs, metrics, and reconciliation result.
- Approved, declined, pending, authentication-required, abandoned, cancelled, and timed-out attempts.
- Double taps, client retries, server retries, duplicate events, delayed events, and events arriving out of expected order.
- Authorization, capture, cancellation, full refund, partial refund, repeated refund, and failed refund where relevant.
- Checkout interruption, expired session, provider outage, fulfilment failure after payment, and notification failure.
- Amount, currency, tax, fee, payout, date-boundary, and manual adjustment mismatches detected by reconciliation.
- Test and live credential separation, webhook secret rotation, least-privilege access, alerts, rollback, and incident ownership.
A one-journey payment integration brief
Before estimating development, complete this worksheet for one purchase and its most important reversal:
- Customer, purchase, amount, currency, and payment methods.
- Checkout pattern and reviewed security/compliance boundary.
- Order, payment, refund, and fulfilment identifiers.
- Provider-to-business state table and fulfilment gate.
- Idempotency, webhook, retry, and unknown-result rules.
- Refund, dispute, reconciliation, and support ownership.
- Acceptance cases, monitoring, go-live, and rollback evidence.
This brief gives a payment API integration partner enough context to challenge risk and estimate a first release without pretending every later payment method is already known.
Frequently asked questions
What should payment gateway integration requirements include?
Include the commercial model, countries and currencies, payment methods, checkout ownership, order and payment identifiers, provider and business state mapping, authentication, authorization and capture rules, idempotency, webhooks, fulfilment gates, refunds and disputes, customer messages, reconciliation, permissions, monitoring, test scenarios, release controls, and accountable owners.
Should an order be fulfilled from the checkout success page?
Not by assumption. A browser redirect can be interrupted or repeated, and some payment methods remain pending. Define the provider evidence that authorizes fulfilment, verify it server-side, make the fulfilment action idempotent, and reconcile later events against the order record.
How do you test a payment gateway integration before launch?
Test approved, declined, pending, abandoned, authentication-required, timed-out, duplicated, delayed, and out-of-order paths. Also test double submission, capture and cancellation, full and partial refunds, webhook verification, fulfilment failure, provider outage, reconciliation mismatches, role permissions, customer messages, monitoring, and production configuration with the provider's supported test tools.