TECHNICAL GUIDE / A2A
A2A payment status, webhooks and reconciliation
A reliable operating model for bank-direct payments: state machine, idempotent webhooks, retry queue, references, refunds and daily reconciliation.
- Last expert review
- 30 July 2026
- Reviewed by
- FoxPay Product & Compliance
01State model
Model states explicitly, not implicitly
Created
Payment exists but bank authorisation is not confirmed.
Pending
The outcome is open; fulfilment remains blocked or deliberately controlled.
Paid
Server-confirmed terminal state for order release.
Failed/expired
Terminal non-payment; a retry receives a new reference.
02Webhooks
Make every event safe and effective once
Signature verification
Validate raw body, timestamp and signature using the documented process.
Idempotency key
Persist the event ID and acknowledge duplicate delivery without side effects.
Acknowledge first
Respond quickly after durable persistence and run heavy work asynchronously.
Out of order
Validate transitions because events can arrive late.
03Reconciliation
Daily matching as a controlled process
Three references
Store merchant order, FoxPay payment and payout/settlement separately.
Differences
Classify missing, duplicate, mismatched or long-pending payments.
Ownership
Technical and financial differences have named owners.
Audit trail
Record status change, event, decision and correction traceably.
04Workflow
Webhook processing
A robust handler separates acceptance, persistence and business processing.
- 01
Receive
Capture the raw request and bounded metadata.
- 02
Verify
Check signature, age and allowed event type.
- 03
Deduplicate
Persist the event ID atomically.
- 04
Process
Apply the state transition idempotently.
- 05
Reconcile
Feed differences into monitoring and daily reconciliation.
05Evidence
Failure and retry matrix
Not every failure should be handled in the same way.
| Failure | Response | Goal |
|---|---|---|
| Timeout | Retry with backoff | Delivery |
| Duplicate | Success without side effect | Idempotency |
| Invalid signature | Reject + alert | Security |
| Invalid transition | Dead letter + review | Correction |
Logs must not contain secrets or unnecessary personal payment data.
06FAQ
Frequently asked questions
Answers for the current, expert-reviewed scope.
Why are webhooks delivered more than once?
At-least-once delivery protects against lost events. The receiver must therefore be idempotent.
Can the browser release the order?
No. The browser may show a preliminary state; the server-confirmed payment controls fulfilment.
How often should reconciliation run?
Frequency depends on volume and operating risk. Daily automated matching plus timely exception handling is a reliable baseline.