Integration reference
Merchant ledger state transition reference
Merchant ledger states, posting gates, and alignment with provider lifecycle labels under finance controls.
01
Ledger states
Merchant ledger state is your internal books representation—aligned to, but not identical with, provider lifecycle labels.
| Ledger state | Meaning | Typical provider prerequisite |
|---|---|---|
| Attributed (unrecognized) | Detected internally | Paid or equivalent |
| Recognized | Finance acceptance for allocation | Confirmed + reconciliation pass |
| Posted | Ledger entry recorded | Finance approval |
| Reserved for payout | Funds earmarked | Payout request validated |
| Paid out | Outbound movement executed | Orchestration complete |
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations