Payment Gateway Integration: Payment States, Webhooks and Reconciliation

A hosted checkout can be a sensible starting point when the merchant has standard payment needs and limited development capacity. A more customised integration may suit a business with specific order, capture or user-experience requirements, provided it can maintain the extra code and operating procedures. Compare the work your team can reliably own, not just the appearance of the payment form.

Outsourcing the collection of card details does not outsource every security responsibility. PCI SSC says merchants retain responsibilities including checking provider compliance, documenting shared duties and validating their own compliance through the applicable programme. Confirm the requirements for the actual implementation with the compliance-accepting entity, such as the acquirer or payment brand. [7]

Write down who maintains the checkout component, server credentials, webhook endpoint, order mapping, refund tools and finance reports. Ask the supplier which tasks its plugin performs and which require your own code or staff. A feature being supported by the gateway does not prove the chosen plugin implements it.

Confirm the live account can use the intended methods, currencies, capture mode and recurring features before building around them. Sandbox availability is useful for development; it does not establish business approval or live enablement.

An order can have several payment attempts, and a successful payment can later have several financial movements. Use separate records joined by stable references. The order describes the purchase and fulfilment. The payment record describes the provider operation. Refunds, fees, disputes and payouts describe later movements that finance must trace.

Stripe’s status documentation illustrates the distinction: requires_action needs another step; processing awaits an asynchronous outcome; requires_capture indicates a separate capture stage; succeeded completes that payment flow. Later refunds and disputes can be reflected on the Charge while the PaymentIntent remains succeeded. [1] A single paid flag therefore cannot serve every operational purpose.

Agree the source of evidence for each transition. Browser messages can inform the customer, while your server controls fulfilment according to the provider’s documented confirmation flow. Store amount and currency alongside references, and check them against the intended purchase before issuing goods or access. Treat a mismatch as an exception requiring investigation.

The table separates questions the merchant needs to answer. It is not a universal sequence: a method may omit a distinct authorisation stage, and partial capture or refund may create several linked operations. Map the table to each enabled flow, including the less common paths that support staff will eventually encounter.

A timeout tells you that a response was not received in time. It does not tell you whether the provider acted. Keep the operation reference and investigate through the supported status and retry mechanisms before starting another charge.

Idempotency makes a supported repeated request behave as the same operation under the provider’s documented conditions. It must be implemented in the outbound request; adding an order number to your own database does not by itself enable it.

Stripe documents different behaviour for API v1 and v2. In v1, a saved response can include an error, parameters must agree, and a key reused after pruning can create a new request; keys can be removed after at least 24 hours. Do not assume v2 has identical retry semantics. [3] Adyen currently documents key validity of 7–14 days, company-account scope and no duplicate checking across different regional endpoints. [4]

Create a fresh key for each intended operation and preserve it for retries of that operation. A capture and a refund need their own operation identities. Specify the provider version, key scope, storage and expiry behaviour in the integration notes. If a retry remains ambiguous, route it to recovery rather than inventing a new key to make the error disappear.

A webhook is a server notification, not proof that your business action completed. Design a durable handoff: verify the message using the provider’s mechanism, save what is needed for recovery, acknowledge according to the delivery contract, and process the order change through a worker. If durable receipt fails, do not report success merely to clear an alert.

Stripe requires the raw request body for signature verification and warns that events can be duplicated or delivered out of order. Its guidance uses event identifiers for repeated deliveries and describes object-and-event-type checks for some separately generated duplicates. [2] Adyen’s current handling guide likewise separates verification, storage, acknowledgement and business processing, with its own event identity guidance. [5]

Protect the fulfilment action as well as the inbox. Two workers can otherwise receive valid events and both release an order. Use a transaction or equivalent concurrency control to make the intended order transition happen once, with a recoverable job for downstream delivery. If a worker fails after changing the order but before acknowledging its job, replay must not ship it again.

Do not force all providers into one timestamp rule. An older event arriving later should not blindly overwrite a newer state. Use the documented resource/version information and retrieve the current provider object when needed. Record uncertain or inconsistent events for investigation instead of discarding them silently.

Suppose order PG-104 is for €120 in a one-time card flow that captures immediately. The server creates the intended payment using operation key K-104, but the connection drops before the response returns. It records the outcome as unknown and shows the customer an accurate checking message rather than a confirmed failure.

The recovery process follows the provider’s supported same-operation retry or lookup. It discovers that payment P-104 succeeded. A verified event E-104 is saved and the order becomes eligible for one fulfilment action. When E-104 arrives again, it produces no second release. If a different event describes the same business transition, the order-level guard still applies.

Later, the customer requests a €20 partial refund. Staff create a separate refund operation R-104 and follow its outcome. The order history retains €120 collected and €20 refunded, with €100 remaining before fees or other adjustments. It does not erase the original payment or claim the refund reached the customer merely because the instruction was submitted.

These references and events are fictional. Turn the sequence into a test using your provider’s real statuses and tools. Assert the final payment, order, fulfilment and refund records—not just that each endpoint returned a success response. Include a worker crash between state change and delivery to test whether the recovery design actually works.

Event handling keeps orders moving. Reconciliation asks whether the records agree even when a notification, report or staff action was missed. Run both processes; neither endpoint uptime nor a balanced bank total proves every order was handled correctly.

First match orders and payment attempts by provider, account, reference, amount and currency. Investigate payments without orders, orders released without the expected evidence, duplicate captures and refunds with no confirmed outcome. Use a controlled recovery job with the provider’s rate limits rather than an unrestricted polling loop.

Then match financial entries to settlement batches. Adyen’s transaction-level guide uses the provider reference and merchant reference to identify transactions and explains that a transaction can have multiple report entries. It bridges net credits and debits to the batch payout; external acquiring can require additional or separate reports. [6]

Finally match the payout reference to the bank receipt. Keep the settlement date, payout instruction and bank value date available to finance. A transfer still in transit belongs in an outstanding-items record, not in the same category as an unexplained missing payment. Separate currencies and accounts before aggregating, and retain a clear explanation of every remaining difference.

Assume a settled batch contains €10,000 of captured receipts. It includes €300 of refunds, €250 of processing charges and €500 newly withheld in reserve. There are no disputes, reserve releases, FX changes or other adjustments. Under these assumptions, the expected payout instruction is €8,950.

The capture-to-payout difference is €1,050, explained by those three deductions. Suppose the bank has received €8,000 by the reporting cut-off, and the remaining €950 is confirmed as in transit on that same payout. The extra €950 difference belongs to payout timing. It should not become another processing fee or a second reserve deduction.

The €8,950 instruction in this exercise is not bank-available cash until received, and the €500 reserve remains tracked separately. Real reports can use different signs, accounting dates and grouping. Finance must map the actual report definitions; this simplified bridge is not a universal provider formula or an accounting policy.

Give the test batch one deliberately missing reference and one duplicate imported line. The reconciliation should surface the missing match and avoid counting the duplicate. Make the team explain the result from individual records. A manually typed balancing adjustment would hide the very failure this test is meant to reveal.

Agree expected outcomes before running the tests. For each method and capture mode, include success, decline, customer abandonment, authentication interruption, uncertain response, delayed notification, duplicate notification and an unavailable worker. Test partial refunds and a failed or pending refund where the method supports them. The table gives starting cases; adapt it to the actual integration.

Keep safe references and timestamps for each run. Product should assess the customer message, engineering the state changes and recovery, support the investigation tools, and finance the final ledger and report match. An untested feature should stay outside the launch promise until its owner can demonstrate it.

Test configuration separation too: sandbox credentials and event destinations must not affect live orders. Limit staff permissions for refunds and changes to settlement details. Plan secret rotation, controlled deployment and rollback, and know which team can contact the provider during an incident. Avoid placing API secrets or full payment credentials in logs and tickets.

Once live, watch unresolved outcomes, event-processing backlog, reconciliation differences and repeated customer contacts as well as HTTP failures. Choose alert thresholds from the business’s obligations and actual baseline. This guide supplies no measured reliability target or promised conversion improvement.