Currencies, rails and providers

Fiat money on this API moves through two banking providers — Fiat Republic and OpenPayd — and every rail field you will meet (rail on account create, on beneficiary create, on withdrawal create and on payout batches) means something slightly different. This page is the one table for all of them, plus the rule that ties an account, its beneficiaries and its withdrawals to one provider.

Currencies

The fiat surface supports GBP, EUR and USD. Fiat account create, beneficiary create and update, and fiat withdrawal create all refuse anything else with 422 unsupported_currency (payout batches enforce their own currency rule — see that route). Conversions use a different list: GBP, USD and EUR plus BTC, ETH, USDC and USDT — see Conversions.

Two refusals sit ahead of everything: a customer in a blocked jurisdiction gets 403 fiat_unsupported_jurisdiction on account create for every currency, and a currency not offered to the customer's type gets 403 currency_not_available_for_customer_type.

Which provider holds an account

You do not pick OpenPayd. POST .../banking/accounts accepts an explicit provider of FIAT_REPUBLIC only (422 unsupported_provider for anything else, OPENPAYD included); when you omit provider, the tenant's routing rules choose, and that is the only way an account is placed with OpenPayd. GET .../banking/accounts/form-schema describes what can be named — it therefore advertises Fiat Republic alone, while its currency and rail lists describe what the platform can do.

Read the account's provider field to learn where it landed. It decides everything downstream.

One account per currency. A customer may hold at most one active fiat account per currency (Pending, PendingProvider, ManualReview or Completed), at any provider. A second request in the same currency at the same provider returns the existing account; at a different provider it is refused with 409 duplicate_currency_account — the detail names the provider and status of the account in the way. To move a currency to the other bank, the existing account has to be closed first.

The provider chain

Provider identity is a chain, not a per-call choice:

1. Account — issued at Fiat Republic or OpenPayd (above).
2. Beneficiary — POST .../banking/beneficiaries creates the payee at each provider where the customer holds an account in that currency that the provider has accepted (provider_account_id set). No such account → 409 bank_account_required. Naming provider narrows the choice to that provider's accounts; it cannot reach a provider the customer has no account with.
3. Withdrawal — POST .../banking/withdrawals is funded from the customer's Completed account at the beneficiary's provider in the withdrawal currency. If there is none (for example the account was routed to OpenPayd but the beneficiary is an old Fiat Republic row, or the account is not Completed yet) the call is refused with 409 source_account_not_ready.

The practical consequence: check provider on the account first, then create beneficiaries only after provider_account_id is set, and expect beneficiaries and withdrawals to follow the account's provider. Details of step 2 are in Beneficiaries.

Identifiers a receiving bank can recognise (OpenPayd EUR/GBP). destination on a withdrawal row is the provider's own internal reference — never quote it to a bank. Once an OpenPayd payout is accepted, the withdrawal read also carries transaction_id (the provider's own transaction id), end_to_end_reference (the SEPA/SWIFT end-to-end reference actually quoted to the receiving bank) and provider_short_id (a short, human-readable reference such as 20220922-K3QY65) — use provider_short_id when reading a reference out over the phone, and transaction_id when escalating to support. All three are null until the provider accepts the payment, null for a provider that does not report one, and null on rows created before this field shipped (except transaction_id, which is recovered from the stored OpenPayd reference where possible).

Rails

Two vocabularies exist, one per provider:

• Fiat Republic uses scheme codes: FPS, CHAPS, BACS (GBP); SCT (EUR); ACH, ACH_SAME_DAY, DOMESTIC_WIRE, INTERNATIONAL_WIRE (USD). Input is normalised — case, hyphens and spaces are tolerated and FASTER_PAYMENTS, SEPA, SEPA_INSTANT, WIRE, FEDWIRE, SWIFT are accepted as aliases — but only the canonical code is stored and echoed.
• OpenPayd uses payment types: FASTER_PAYMENTS, CHAPS (GBP); SEPA, SEPA_INSTANT (EUR). FPS is accepted for FASTER_PAYMENTS; SCT is accepted and means standard SEPA, not SEPA_INSTANT.
• OpenPayd EUR and GBP over SWIFT: explicit international transfers, enabled separately for each currency and verified bank destination. SWIFT is never a default. Obtain the available destinations from GET /api/v2/dashboard/banking/swift-options (or the equivalent partner customer route). Create an OpenPayd beneficiary with rail=SWIFT, the recipient bank country, exactly one IBAN or account number as specified by that destination, a BIC and the beneficiary's own address. The optional intermediary field is a BIC only; additional routing codes, bank or intermediary addresses and address state are not supported on this route. Combined address lines may contain at most 255 characters. purpose_code is not exposed by the withdrawal API. SWIFT beneficiaries cannot be paid through a domestic rail or a payout batch.
• Before sending SWIFT, obtain GET /api/v2/dashboard/banking/swift-quote?beneficiaryId=...&amountMinor=... (or the equivalent partner customer route). Submit its feeMinorString as expectedSwiftFeeMinor and its feeConfigurationVersionId as swiftFeeConfigurationVersionId. The v1 request uses expected_swift_fee_minor and swift_fee_configuration_version_id. A new request with a changed fee is refused before a payment is claimed. A timeout must be retried with the same idempotency key and entire original payload, including the accepted fee version. Do not obtain a new quote for an unresolved request. Expect 2–5 working days; intermediary or receiving banks may deduct their own charges from the amount received.

Which one applies is decided by the provider of the beneficiary (withdrawals) or of the routed account (accounts), never by the value you send.

What each route does with rail:

Per-rail limits and scheme notes

• OpenPayd Faster Payments is capped at GBP 1,000,000 per payment. An amount above it is not refused: the withdrawal returns 200 with status Failed and the funds released. Use CHAPS, which has no cap, for larger GBP payments.
• EUR at OpenPayd: SCT and SEPA select standard SEPA Credit Transfer; omitting the rail selects SEPA_INSTANT. Send SEPA_INSTANT explicitly if that is what you want.
• Payment references (description on a withdrawal) are checked before the hold for USD at Fiat Republic and supported OpenPayd payment types. OpenPayd requires ASCII and a byte cap of 18 for Faster Payments, 35 for CHAPS/SWIFT and 140 for SEPA. Invalid references return 422.
• OpenPayd EUR/GBP SWIFT preflight checks the enabled route, stored beneficiary, owned source account and accepted fee before a new payment is claimed or held. A preflight refusal returns 422 swift_preflight_failed; an idempotent replay retains the original payment and fee.
• Inbound: money reaches an issued account as a credit transfer and lands as a deposit.received webhook. SEPA Direct Debit is not supported on EUR accounts.

Conversions

POST .../banking/conversion-requests converts between the customer's balances. The asset list is GBP, USD, EUR, BTC, ETH, USDC and USDT, with three rules:

1. from_currency and to_currency must differ.
2. A BTC or ETH source converts to fiat only — BTC→USDC, ETH→USDT, BTC→ETH and the like are refused with 422 invalid_pair. Fiat, USDC and USDT sources may target any other listed asset.
3. Fiat, USDC and USDT sources have a 20 major-unit minimum (422 below_minimum_trade_size).

The customer must already hold a Completed fiat account (fiat side) or an active wallet (crypto side) for both assets — 409 exchange_account_missing / exchange_wallet_missing otherwise; this route opens neither.

GET /api/v1/partner/transfer/allowed-destinations lists the assets the exchange can deliver for your tenant; it is derived from the tenant's exchange fee configuration and is empty when no exchange fee is configured. Pass source_currency to have the pair rules applied for you. GET /api/v1/partner/transfer/price is indicative only: the conversion executes at the live rate and references nothing from the quote.