Reconcile Inbound Settlements

Use this flow when your integration receives inbound settlement webhooks and you need to acknowledge delivery fast, deduplicate retries, and update internal balances or orders only when an event reaches the completed state.

✅ Before you start

Complete these steps before you reconcile inbound settlements:

Authenticate with the merged Login service and store the returned token and companyId.
Identify the wallets that should receive inbound settlements and confirm the sub-account context for each.
Register a public HTTPS webhook endpoint subscribed to the receive events your flow depends on.
Provision a deduplication store (Redis, database table, or equivalent) keyed by webhook event_id.
Decide which internal state changes (ledger credit, order release, sweep trigger) should run only after the event reaches completed.

📚 Use this page with the recipe

This guide explains when to use the inbound settlement reconciliation flow and the minimum sequence. For the implementation walkthrough, use the recipe:

Reconcile Inbound Settlements with Webhooks Recipe →

The reconciliation workflow

This use case follows a strict sequence:

Register the webhook endpoint and subscribe to the receive events you depend on.
Acknowledge each delivery fast with a 200 OK response before doing any work.
Deduplicate by event_id so retries of the same event are no-ops on internal state.
Update internal state only when the event reaches completed and matches it back to the wallet, sub-account, or order context.
Reconcile the resulting balance against the statement view to catch missed or duplicated events.

What makes this use case different?

Unlike a synchronous payout flow, inbound settlement reconciliation needs to:

tolerate webhook retries without creating duplicate ledger entries
defer any balance or order mutation until the event status is completed
match events back to the correct wallet, sub-account, or order using the payload reference
operate continuously rather than as a one-off request/response sequence

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Troubleshooting

Issue	What to check
Verto retries the same event repeatedly	Confirm the endpoint returns `200 OK` quickly, before any downstream work runs.
Duplicate ledger entries appear	Deduplicate by `event_id` with a persistent store, and guard ledger writes with an idempotent check.
Balance updates before funds are usable	Mutate internal state only when the event status is `completed`, not on intermediate states.
Event cannot be matched to an order or wallet	Verify the payload `reference` and `wallet_id` against your internal records and the sub-account context.
Wallet balance drifts from the statement	Reconcile periodically against the statement view to detect missed or duplicated events.

Next steps


Receive → Handle inbound settlement events and reconcile wallet credits safely.	Webhook Event Handling → Route webhook events to the correct internal workflow and acknowledge delivery fast.

Talk to Verto

Get help with authentication, receive flows, wallets, FX conversion, payouts, or Atlas platform setup.

Plan your go-live

Review the requirements you need before moving your integration into production.