Payment Flow Technical Specification Template

Network failures, timeouts, and client retries can cause the same payment request to arrive at the processor multiple times. Without an idempotency key, each request creates a new charge, resulting in double-billing. The idempotency key tells the processor "if you have already processed a request with this key, return the original result instead of creating a new transaction." Every payment API call that creates or modifies a transaction should include one. Use a [risk assessment](/templates/risk-assessment-template) to identify where duplicate transactions could occur in your system.

Authorization verifies that the customer's payment method is valid and has sufficient funds. It places a hold on the funds but does not move money. Capture is the step that actually transfers the funds. Some flows authorize and capture simultaneously (a "sale"). Others authorize first and capture later (common in e-commerce where you authorize at checkout and capture at shipment). The gap between authorization and capture is typically limited to 7 days for card payments before the authorization expires.

3DS adds an authentication step where the cardholder verifies the transaction with their bank (via SMS code, biometric, or app notification). Your flow must handle three outcomes: the customer completes 3DS (proceed to capture), the customer abandons 3DS (cancel the authorization, show a retry option), or 3DS fails (treat as a decline). For [SCA-compliant](/glossary/prioritization) transactions in Europe, 3DS is mandatory unless an exemption applies.

Daily reconciliation is the standard for any payment system processing more than a few transactions per day. Match your processor's settlement reports against your internal transaction ledger every morning. Monthly reconciliation catches drift that daily checks miss (timing differences, fee discrepancies, currency conversion rounding). For high-volume systems (thousands of transactions per day), automated reconciliation with exception-based alerts is more effective than manual review.

Combine idempotency keys with a clear retry policy. Generate the idempotency key on the client before the first attempt. Reuse the same key for all retry attempts of the same logical transaction. Set a reasonable TTL for the key (24-48 hours). Only retry on network errors and soft declines, never on hard declines (fraud, invalid card). Cap retries at 3-4 attempts with exponential backoff to avoid hammering the processor. ---