Skip to main content

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.

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.

ActionRequested action
debit_balanceDeducts funds from a customer’s balance for settlement.
credit_balanceAdds funds to a customer’s balance (for refunds or adjustments).
hold_balancePlaces a hold on funds in a customer’s balance (pre-authorization).
restore_balanceReleases previously held funds back to the available balance.
debit_hold_balanceDeducts an amount from previously held funds (created with hold_balance).
credit_hold_balanceAdds 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 a TenantLedgerRequest body. A payload mapping, if you configured one, reshapes the body.
  • Who: account_id is Open Fabric's account ID; tenant_account_ref and tenant_customer_ref are your references; customer_id is Open Fabric's customer ID.
  • Amounts: decimal numbers in major units (1500 for JPY 1,500, 12.5 for SGD 12.50). amount is in the transaction currency, currency.
  • Billing amount: when present, billing_amount is 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 optional network_lifecycle_ref (your hold reference, on hold_balance), available_balance, hold_balance and currency.
  • 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.