Ledger APIs
In this integration mode, Open Fabric converts network events into ledger operations (debit/credit/hold/release) and calls your backend via API to apply them. You do not need to download or process clearing files.
What you build
- Real-time authorization: Open Fabric forwards authorization requests to you; you approve/decline with sub-second latency.
- Ledger operations: Open Fabric calls your backend to apply balance operations (debit/credit/hold/release).
- Settlement: You receive end-of-day settlement. Open Fabric provides settlement reports to reconcile settled funds against the ledger operations performed.
- See Settlement
What Open Fabric handles
- Authorization: When we receive authorization requests, we ask you for approval. Successful approvals trigger the required ledger action(s).
- Reversals and expiries: When reversals or expiries occur, Open Fabric triggers compensating ledger actions.
- Clearing file updates: When clearing updates arrive from the network, Open Fabric reconciles the transaction and triggers any remaining ledger actions required to complete the lifecycle.
When to choose this mode
- You want an API-first integration that fits wallet/ledger systems.
- You prefer Open Fabric to normalize network message types and timing differences into a consistent set of operations.
Ledger operations
Open Fabric informs you when to make changes to your customers' accounts. This can be the result of a payment you've approved, but also due to reversals, expiries or clearing file updates.
Please implement the following ledger actions in your system.
| Action | Requested action |
|---|---|
debit_balance | Deducts funds from a customer’s balance for settlement. |
credit_balance | Adds funds to a customer’s balance (for refunds or adjustments). |
hold_balance | Places a hold on funds in a customer’s balance (pre-authorization). |
restore_balance | Releases previously held funds back to the available balance. |
debit_hold_balance | Deducts an amount from previously held funds (created with hold_balance). |
credit_hold_balance | Adds an amount to previously held funds (created with hold_balance). |
An incremental pre-authorization raises an existing hold. It arrives as a hold_balance call with network_lifecycle_ref set to that hold, so there is no separate endpoint to build.
How Open Fabric calls you
- Request:
POST {base_url}/<action>, for example/hold_balance, with aTenantLedgerRequestbody. A payload mapping, if you configured one, reshapes the body. - Who:
account_idis Open Fabric's account ID;tenant_account_refandtenant_customer_refare your references;customer_idis Open Fabric's customer ID. - Amounts: decimal numbers in major units (
1500for JPY 1,500,12.5for SGD 12.50).amountis in the transaction currency,currency. - Billing amount: when present,
billing_amountis the same money in your account's currency,billing_currency, rounded half-up to that currency's decimals. Move the account by it. It is sent only on an operation for the full authorization amount. Apply an operation without it at the authorization's rate (billing_amount/amount), and when an operation settles the whole remaining hold, release or debit all of it. - Idempotency: a retry of an operation carries the same
metadata.idempotency_key. Apply each key once. - Optional fields may be absent on transactions that started before Open Fabric sent them.
How to answer
Answer with a TenantLedgerResponse:
- Success:
{"status": "success", "transaction_ref": "..."}, plus optionalnetwork_lifecycle_ref(your hold reference, onhold_balance),available_balance,hold_balanceandcurrency. - Refusal:
{"status": "failure", "error_code": "...", "message": "..."}with a 4xx. A 4xx is final.
A 2xx failure is final unless its code is INTERNAL_ERROR or unknown. A 5xx, a timeout, an unreachable endpoint or a body that doesn't match the schema is retried.
error_code should be one of:
ACCOUNT_NOT_FOUND,ACCOUNT_MISMATCH;INSUFFICIENT_BALANCE,INSUFFICIENT_HOLD_BALANCE;HOLD_NOT_FOUND,HOLD_NOT_ACTIVE,HOLD_RESTORED,LIFECYCLE_REQUIRED;RESTORE_EXCEEDS_HOLD,DEBIT_EXCEEDS_HOLD,CREDIT_EXCEEDS_DEBITED;AMOUNT_REQUIRED,VALIDATION_ERROR,UNAUTHORIZED,INTERNAL_ERROR.
Any other code is treated as INTERNAL_ERROR.
See the Ledger operations API in our API reference for details.