Migrating from the Integrated Finance API
Resource and convention mapping for integrations built against Integrated Finance.
Operators that move to WireBloom from a direct Integrated Finance (IF) integration can port their integration resource by resource. WireBloom sits in front of the banking partner: your system talks only to the WireBloom API, whichever partner the operator runs.
Resources
| Integrated Finance | WireBloom | Reference |
|---|---|---|
client | customer (X-Tenant-Id) | Tenancy |
bankAccount / transactionAccount | balance | listBalances |
outgoingTransfer | payment | createPayment |
exchange | exchange (quote, then exchange) | createExchange |
beneficiary | recipient | createRecipient |
webhook envelope {webhook, data, connect, metadata} | IntegratorEvent | Event catalogue |
Conventions
| Topic | Integrated Finance | WireBloom |
|---|---|---|
| Idempotency | X-Idempotency-Key, X-Idempotency-Status | Idempotency-Key, Idempotency-Replayed: true (Idempotency) |
| Pagination | 0-based metadata.page | opaque cursors page.nextCursor (Pagination) |
| Filters | dotted, e.g. data.client.status= | filter[status]= |
| Errors | not catalogued | RFC 9457 problem details, error catalogue |
| Webhook signatures | Ed25519 with published keys | HMAC-SHA256 with your endpoint secret (Webhooks) |
| Webhook registration | two fixed URLs per instance, set by IF | self-service, up to 10 endpoints per customer |
| Custom data | attributes | metadata (20 keys, 500 characters per value) |
Steps
- Map your stored IF ids to WireBloom ids (customers, balances, recipients); keep both during the cut-over.
- Replace polling of IF transfer statuses with the
payment.status_changedwebhook and re-read the payment. - Replace IF webhook verification with the HMAC check and de-duplicate on
WireBloom-Event-Id. - Run the whole flow against the sandbox with a
wb_test_key before switching production keys.