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:
| Part | When | Contents |
|---|---|---|
entry | Money moved | type (hold, hold_change, hold_release, debit or credit), amount, entry_id, and hold_ref for an entry that changes or settles a hold |
transaction | The 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 |
balance | Optional | The 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
kind | Typical statuses |
|---|---|
card | authorized → cleared, or declined, reversed, refunded. credited for a merchant refund with no original payment |
qr | pending → completed, or declined, failed |
payout | sent → settled, or failed, returned |
transfer, fee, interest, adjustment, other | completed |
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
clearedthat arrives before itsauthorizedstill clears the payment. - Idempotent on
event_id. A repeated event is acknowledged asduplicateand not applied again. Derive theevent_idfrom the message that caused it (for example the issuer processor'snotification_idor the clearing record'snetwork_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:
status | Meaning | What you do |
|---|---|---|
applied | Recorded | Nothing |
duplicate | This event_id was already received | Nothing |
ignored | Valid, but nothing to do. For example the account isn't linked to a business. code says why | Nothing |
rejected | Permanent failure: invalid_event (with the failing field), currency_mismatch, unknown_card or refund_exceeds_cleared | Don'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 message | Your ledger | Account event |
|---|---|---|
| Pre-authorization, approved | Hold | hold + authorized |
| Final authorization, approved | Hold until it clears | hold + authorized |
| Authorization, declined | None | declined with decline details |
| Incremental pre-authorization | Raise the hold by the increase | hold_change for the increase, still authorized |
Notifications
| Notification | Case | Your ledger | Account event |
|---|---|---|---|
| Pre-auth reversed | Part of the hold | Reduce the hold | hold_change, still authorized |
| Pre-auth reversed | The rest of the hold, nothing cleared | Release the hold | hold_release + reversed |
| Final auth reversed | Still held | Release the hold | hold_release + reversed |
| Final auth reversed | Already cleared | Credit, capped at what was cleared | credit + refunded |
| Authorization failed | You had approved it | Release the hold | hold_release + reversed |
| Clearing file ready, settlement file ready | Download the file and apply each record (below) | Per record |
Clearing and settlement records
| Record | Your ledger | Account event |
|---|---|---|
pre_auth_final, final_auth | Debit the cleared amount, release the rest of the hold | debit + cleared |
pre_auth_partial, final_auth_partial | Add to the cleared total; the hold stays | None until the final clearing |
pre_auth_expiry, final_auth_expiry (nothing cleared) | Release the hold | hold_release + reversed |
refund, final_auth_reversal after clearing | Credit, capped at what was cleared | credit + refunded |
unlinked_refund | Credit the account | credit + credited, on a new ref |
| Settlement detail for a final auth that is still held | Debit, release the hold | debit + cleared |
| Chargebacks, fee collection and other records | Your own process | None |
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.