Callbacks
How Bankrail notifies your service — signed, retryable, idempotent by header — when a credit lands or a transfer settles.
Bankrail notifies your service by callback when a credit lands on an intent or virtual account, and when an outbound transfer reaches a terminal state. Callbacks are signed, retryable, and idempotent by header.
What you receive
Bankrail POSTs to the callbackUrl you supplied when creating the instrument. The body
describes the event — for a credit, the amount, the receiving account or intent, and (for
a BRR-bearing instrument) the brr. For an outbound transfer, the terminal settlement
state.
Verify the signature
Every callback is signed. Verify the signature before trusting the body — it's how you confirm the notification genuinely came from Bankrail and was not tampered with.
Idempotency
Callbacks are idempotent by header: Bankrail may deliver the same event more than once (retries on network failure), and a delivery carries a stable idempotency header. Use it to deduplicate — process each event exactly once even if it arrives twice.
Retries
If your endpoint doesn't acknowledge a callback, Bankrail retries delivery. Make your handler idempotent and return a success status only once you've durably recorded the event.
Reconciling with BRR
For BRR-bearing instruments, every credit-confirmed callback carries a brr field you
reconcile against — a single reference for one value movement from issuance through credit
and settlement. See BRR.
Next
- BRR — the reconciliation reference.
- Virtual Accounts — testing callbacks in sandbox.