Balansas sits in front of banking infrastructure that settles asynchronously. Most operations are processed immediately, but some — payments, settlements, compliance review — take time to reach a final state. Design your integration around eventual consistency rather than expecting every read to be instantly authoritative.

​
Data freshness

Balances and resource statuses are kept current through two mechanisms:
  • Webhooks — the platform pushes an event the moment a state change occurs.
  • Periodic sync — a background reconciliation refreshes data from the banking infrastructure on a schedule.
Between these updates, a read may return a value that is slightly behind reality (for example, a balance that doesn’t yet reflect a deposit that just arrived). Treat every list or detail read as a point-in-time snapshot, not a live guarantee.

​
Rely on webhooks for state changes

For anything that changes over time — a payment moving from pending to completed, a wallet send confirming on-chain — subscribe to the relevant events instead of polling.

Webhooks

Subscribe to signed, retried event delivery for state changes.

Transactions

Read the status field to confirm where a transaction stands.
Do not poll a list endpoint in a tight loop waiting for a status to change. It wastes your rate-limit budget and can still miss short-lived intermediate states. Subscribe to a webhook and react to the event.

​
Confirm completion via status

Never infer that an operation finished just because the request returned 2xx. Always check the resource’s status. EU Rails transaction statuses are:
StatusMeaning
pendingInitiated, awaiting processing
completedSuccessfully processed
failedFailed or rejected
compliance_reviewHeld for compliance review
When verifying that a downstream action succeeded, prefer a reject-list over an allow-list: treat known-bad statuses (failed, rejected) as failures and treat a missing or unrecognised status as success. See Errors for the rationale.

​
Validate against live data before moving money

A cached or recently-read balance can be stale. Before any decision that depends on funds being available (a payment or wallet send), validate against the latest balance rather than a value you fetched earlier and held onto.
A locally-cached balance is fine for display hints (“Available: …”), but not as the source of truth for a blocking check. Re-read just before you act.

Idempotency

Make the retries that eventual consistency forces on you safe.