# 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](/docs/tenancy)                                   |
| `bankAccount` / `transactionAccount`                  | balance                         | [`listBalances`](/reference/accounts#listBalances)         |
| `outgoingTransfer`                                    | payment                         | [`createPayment`](/reference/payments#createPayment)       |
| `exchange`                                            | exchange (quote, then exchange) | [`createExchange`](/reference/payments#createExchange)     |
| `beneficiary`                                         | recipient                       | [`createRecipient`](/reference/recipients#createRecipient) |
| webhook envelope `{webhook, data, connect, metadata}` | `IntegratorEvent`               | [Event catalogue](/events)                                 |

## Conventions

| Topic                | Integrated Finance                          | WireBloom                                                                          |
| -------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
| Idempotency          | `X-Idempotency-Key`, `X-Idempotency-Status` | `Idempotency-Key`, `Idempotency-Replayed: true` ([Idempotency](/docs/idempotency)) |
| Pagination           | 0-based `metadata.page`                     | opaque cursors `page.nextCursor` ([Pagination](/docs/pagination))                  |
| Filters              | dotted, e.g. `data.client.status=`          | `filter[status]=`                                                                  |
| Errors               | not catalogued                              | RFC 9457 problem details, [error catalogue](/errors)                               |
| Webhook signatures   | Ed25519 with published keys                 | HMAC-SHA256 with your endpoint secret ([Webhooks](/docs/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

1. Map your stored IF ids to WireBloom ids (customers, balances, recipients); keep both during the cut-over.
2. Replace polling of IF transfer statuses with the `payment.status_changed` webhook and re-read the payment.
3. Replace IF webhook verification with the HMAC check and de-duplicate on `WireBloom-Event-Id`.
4. Run the whole flow against the [sandbox](/docs/sandbox) with a `wb_test_` key before switching production keys.