Skip to main content

Account events

Account events tell Expense Management what happened on a business's funding account. Expense Management uses them to build each expense, keep employee totals and budgets up to date, show payment statuses in the app, and track reimbursements.

One endpoint covers everything on the account: card payments, QR payments, payouts, transfers, fees, interest and adjustments.

Endpoint: POST {expense_api_base_url}/v1/spend/bank_integration/account_events

See the Receive account events API in our API reference for the full schema.

What an event contains​

Each event has an event_id, the account_ref, an occurred_at timestamp and up to three parts:

PartWhenContents
entryMoney movedtype (hold, hold_change, hold_release, debit or credit), amount, entry_id, and hold_ref for an entry that changes or settles a hold
transactionThe money belongs to a transaction, or a transaction changed status without money moving (for example a decline)kind, your ref, status, the check_id, payer, merchant, card or qr details, and decline details
balanceOptionalThe available and current balance after the event

Add a per-account sequence number if you can. Expense Management uses it to detect missed events.

{
"events": [
{
"event_id": "EVT-000981",
"account_ref": "acc_7f3e",
"sequence": 981,
"occurred_at": "2026-11-04T09:15:01Z",
"entry": {
"entry_id": "PST-000981",
"type": "hold",
"amount": { "amount": "280.00", "currency": "SGD" },
"hold_ref": "HLD-000981"
},
"transaction": {
"kind": "card",
"ref": "TXN-778812",
"status": "authorized",
"check_id": "CHK-20261104-000123",
"payer": {
"business_ref": "biz_01jbty0z0tfcz9mg0x5gxmmqv2",
"card_ref": "card_01jbty0z0tfcz9mg0x5gxmmqv4"
},
"merchant": { "name": "Marina Bay Hotel", "mcc": "7011", "country": "SG" },
"card": {
"of_transaction_id": "9f1c2d3e-4b5a-6789-8abc-def012345678",
"last4": "4242",
"authorization_code": "A1B2C3",
"network": "visa"
}
},
"balance": {
"available": { "amount": "49720.00", "currency": "SGD" },
"current": { "amount": "50000.00", "currency": "SGD" }
}
}
]
}

Transaction kinds and statuses​

kindTypical statuses
cardauthorized → cleared, or declined, reversed, refunded. credited for a merchant refund with no original payment
qrpending → completed, or declined, failed
payoutsent → settled, or failed, returned
transfer, fee, interest, adjustment, othercompleted

For a QR payment or payout that Expense Management started, set transaction.expense_mgmt_ref to the payment_ref or reference it sent you. See Core ledger APIs.

For a decline, set transaction.decline with a code and a source: expense_mgmt (Expense Management's check declined), bank (your own reasons, including a stand-in), of_ruleset, of_platform or network. A decline has no entry, so send the amount in transaction.amount.

Delivery​

  • Batches of 1 to 100 events. You can also send one event at a time.
  • At least once, in any order. Expense Management applies each transaction's statuses by precedence, not by arrival. A cleared that arrives before its authorized still clears the payment.
  • Idempotent on event_id. A repeated event is acknowledged as duplicate and not applied again. Derive the event_id from the message that caused it (for example the issuer processor's notification_id or the clearing record's network_clearing_ref), so a crash and retry can't post a second event.

The response​

You get one result per event, in the order you sent them:

statusMeaningWhat you do
appliedRecordedNothing
duplicateThis event_id was already receivedNothing
ignoredValid, but nothing to do. For example the account isn't linked to a business. code says whyNothing
rejectedPermanent failure: invalid_event (with the failing field), currency_mismatch, unknown_card or refund_exceeds_clearedDon't retry. Fix the cause and send a new event

A 5xx or a timeout on the whole call means you retry the batch with backoff. This is safe because every event is idempotent. A 400 on the whole batch means the batch itself was malformed, for example an item without an event_id.

Mapping Open Fabric Issuing messages​

With Open Fabric Issuing in Authorization and Clearing mode, you receive real-time authorizations, event notifications, clearing files and settlement files from Open Fabric Issuing. Apply each one to your ledger, then post the matching account event.

Find the payment with original_tenant_transaction_ref (the reference you returned at authorization). If that is missing, use original_transaction_id. Acknowledge every notification first, then apply it. Use notification_id and network_clearing_ref as idempotency keys.

Authorizations​

Open Fabric Issuing messageYour ledgerAccount event
Pre-authorization, approvedHoldhold + authorized
Final authorization, approvedHold until it clearshold + authorized
Authorization, declinedNonedeclined with decline details
Incremental pre-authorizationRaise the hold by the increasehold_change for the increase, still authorized

Notifications​

NotificationCaseYour ledgerAccount event
Pre-auth reversedPart of the holdReduce the holdhold_change, still authorized
Pre-auth reversedThe rest of the hold, nothing clearedRelease the holdhold_release + reversed
Final auth reversedStill heldRelease the holdhold_release + reversed
Final auth reversedAlready clearedCredit, capped at what was clearedcredit + refunded
Authorization failedYou had approved itRelease the holdhold_release + reversed
Clearing file ready, settlement file readyDownload the file and apply each record (below)Per record

Clearing and settlement records​

RecordYour ledgerAccount event
pre_auth_final, final_authDebit the cleared amount, release the rest of the holddebit + cleared
pre_auth_partial, final_auth_partialAdd to the cleared total; the hold staysNone until the final clearing
pre_auth_expiry, final_auth_expiry (nothing cleared)Release the holdhold_release + reversed
refund, final_auth_reversal after clearingCredit, capped at what was clearedcredit + refunded
unlinked_refundCredit the accountcredit + credited, on a new ref
Settlement detail for a final auth that is still heldDebit, release the holddebit + cleared
Chargebacks, fee collection and other recordsYour own processNone
Some edge cases are still being confirmed

The rows above cover the common lifecycle. For partial clearings combined with reversals or expiries, and for refunds that arrive before the payment clears, ask your Open Fabric contact.

Everything else on the account​

Post events for other activity on the funding account too. Fees, interest, transfers and adjustments show in the business's account activity and in finance exports. A card or QR payment that never had an authorization check, for example during your stand-in, is evaluated after the fact and flagged for review if it is out of policy.

Filling gaps​

If you send sequence, Expense Management alerts on a gap and calls your account event list to fill it, if you offer it. Otherwise it waits for redelivery. A gap never blocks other events.