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.
- Product status checked
- 16 September 2026
- Reviewed by
- FoxPay product documentation
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
Atomically guard the payment reference, event type and state transition. A new delivery ID per attempt alone cannot prevent duplicate business actions.
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
Atomically store the business event key and applied transition.
- 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.
Can I query payment status through the merchant API?
Additional merchant polling access is not currently enabled for general use. Use signed webhooks; separate enablement and current interface rules are documented in the API reference.
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.