Reference model, not a live API
WorldPayAPI.com publishes implementation patterns and neutral schemas. It does not operate the example endpoints below. Use them to clarify resource boundaries before mapping a real processor, bank, custodian, or blockchain provider into your system.
Canonical resources
Payment intent: the commercial request, accepted route families, pricing amount, expiration, and fulfillment state. Payment attempt: one rail-specific instruction and its lifecycle. Settlement evidence: the bank, processor, wallet, or chain reference that proves what the rail reported. Ledger transaction: balanced financial entries. Case: an exception, dispute, compliance review, return, or manual resolution.
Do not make provider objects the primary identifiers. Keep a stable internal ID and store provider references in typed adapters. This lets the merchant contract remain consistent when a route changes.
Idempotent creation
POST /v1/payment_intents
Idempotency-Key: merchant-order-2048
{
"amount": {"value": "1250.00", "currency": "USD"},
"merchant_reference": "order-2048",
"accepted_route_families": ["card", "ach", "stablecoin"],
"expires_at": "2026-10-21T23:00:00Z"
}Persist the idempotency key with a request hash and the original response. Repeating the same key and body returns the same resource. Reusing the key with different parameters fails. Apply the same contract to refunds, payouts, account changes, and sensitive operator actions.
State separation
Keep commercial_state, rail_state, risk_state, ledger_state, conversion_state, and payout_state separate. A bank payment can be submitted but not settled. A stablecoin transfer can be confirmed but held. A card can be captured while the merchant payout remains pending.
Every transition should produce an immutable event with the source, time, previous state, next state, reason, and policy version. Operators should act through commands that create events rather than editing rows.
Signed webhooks
{
"id": "evt_01J...",
"type": "payment.available",
"object_version": 9,
"created_at": "2026-10-21T19:32:11Z",
"data": {"payment_intent_id": "pay_01J..."}
}Sign the raw body with a rotating secret and include a delivery timestamp. Receivers verify the signature, reject stale replays, store processed event IDs, acknowledge quickly, and fetch the current object when sequence matters. Keep the durable event separate from delivery attempts so a missed event can be replayed without inventing a new business fact.
Capability schema
A route capability can declare method family, asset, network, customer action, authorization mode, exact-amount support, partial-payment support, refund support, dispute or return behavior, fee model, reference fields, confirmation profile, eligible entities, currencies, and operational status. Version capabilities and attach the selected version to the payment attempt.
Never use capabilities to imply legal eligibility. The application still needs an approved corridor and provider account configuration.
Ledger commands
Expose named financial operations to internal services: recognize collection, make merchant funds available, accrue fee, hold reserve, initiate payout, record return, issue refund, record dispute, and post adjustment. Each command produces balanced entries and references the payment or case. The ledger rejects arbitrary account combinations from product services.
Use currency and asset definitions with precision and rounding rules. Keep network fees, processor fees, FX differences, platform revenue, customer balances, merchant payables, reserves, and settlement accounts separate.
Reconciliation jobs
Compare three views: application objects, ledger control accounts, and external rail evidence. Run incremental checks throughout the day and a close process at a defined cutoff. Create exception records for missing events, duplicate credits, amount differences, unsettled batches, custody differences, unconfirmed chain transfers, returned payouts, and orphaned refunds.
Do not let a reconciliation script edit historical entries. It should propose or post approved adjustments with links to the discrepancy and evidence.
Production negative tests
- Client retries before and after receiving a response.
- Duplicate, delayed, and out-of-order webhooks.
- Provider timeout after a request may have succeeded.
- Partial, excess, duplicate, late, and unsupported payments.
- Return or dispute after funds became provisionally available.
- Wrong network, token, bank destination, memo, or reference.
- Secret rotation, revoked credentials, and unauthorized operator action.
- Ledger imbalance, external statement difference, and failed adjustment approval.
- Route pause during an in-flight payment and recovery afterward.
Observability and support
Use one correlation identifier across API logs, provider requests, webhook deliveries, ledger entries, support cases, and reconciliation exceptions. Dashboards should show state age and exception age, not only volume. Support tools should mask sensitive data while presenting enough evidence to explain the payment.
Publish status definitions, retry guidance, maintenance behavior, change notices, and incident updates to integrators. Developer experience includes operational predictability, not just clean endpoint names.
