Skip to main content
External accounts are off-platform funding and payout endpoints: bank accounts, external wallets, and debit cards. Each is referenced by ID on a quote side. OMS never holds funds in an external account; it is only a source or destination reference on a transaction. A quote’s source is always an OMS wallet or a card, so banks are always destinations. Cards can be either a source (pull-from-card) or a destination (push-to-card). External wallets are crypto destinations. An external account belongs either to a customer directly or to one of the customer’s counterparties (a saved third-party payee). You register accounts with POST /external-accounts and reference the returned ext_ ID on quotes.

Supported types

Every external account ID carries the same ext_ prefix, whatever the instrument. The type field tells you which instrument type to select on the quote side.

Referencing an external account in a transaction

Reference the external account ID in the quote’s destination (or source, for cards). The instrument is typed by type, and the id in details carries the ext_ prefix.

US bank destination

The US bank network is one of ach, achSameDay, wire, rtp, or instant, limited to the rails the account lists in supportedDestinations. With instant, name the instant rail in instantRail (rtp or fednow). IBAN (bankIban) and Canadian (bankCanada) destinations follow the same pattern with their respective ext_ IDs.

External wallet destination

For an external wallet on a quote you supply exactly one of id (a registered external account, ext_ prefix) or blockchainAddress (a raw on-chain address). Which form a route accepts depends on its corridor: a card source takes either; a crypto source takes id, and on supported crypto-to-crypto corridors it also takes blockchainAddress; and a route that cannot deliver to an external wallet rejects id with WalletExternalIDUnsupported. A crypto-to-crypto quote that supplies a raw blockchainAddress on a corridor the route cannot deliver returns 422 CryptoToCryptoExternalAddressUnsupported. On a corridor that does deliver it, the address is validated like a walletExternal registration (checksum, zero-address, and supported network); a malformed address returns 400 InvalidWalletAddress, the zero address returns 400 ZeroAddressNotAllowed, and a network the route cannot send on returns 422 DestinationNetworkNotSupportedByProvider.

Card source or destination

A card requires asset: usd; its network is inferred server-side. Reference it as the source to pull from a card or as the destination to push to one. See Debit cards for both directions.

Registering external accounts

Register external accounts with POST /external-accounts. The body carries an owner, a type, and exactly one per-type detail object whose key matches type; a mismatch is rejected with 422. Optional label and metadata fields round out the request. The create endpoint accepts type: bankUs, bankIban, bankCanada, or walletExternal. Cards are not valid on POST /external-accounts: they register only through the secure card fields of the OMS browser SDK. See Register a card. The owner selects who the account belongs to:
  • { "kind": "customer", "customerId": "cst_..." } for an account owned by the customer.
  • { "kind": "counterparty", "counterpartyId": "ctp_..." } for an address-book entry owned by one of the customer’s counterparties.

Checking requirements before registering

What a registration needs depends on your project’s configuration. GET /reference/account-type-requirements returns, for each type your project can create, the owner fields and detail fields with a level of required, recommended, or optional, plus the project capabilities the type needs. A type missing from requirements cannot be created on your project. Pass customerId to resolve bankUs for a specific customer; without it, a bankUs entry that depends on the customer carries routingDependsOnCustomer: true and shows the conservative default. Cards are never listed.

Per-type fields

Per-type required and optional fields: When your project requires custodian and the request omits it, create returns 422 CustodianRequired. When your project does not require it, the response omits details.custodian if you did not send one. Reads return the custodian in lowerCamelCase: SELF_HOSTED reads back as selfHosted, and OTHER as other. An external wallet is registered per network family: an EVM address registered once is valid across every EVM chain. For networkFamily: tron, the blockchainAddress must be a mainnet Base58Check address (leading T, case-sensitive); the zero account is rejected. A new account starts pending and moves to active once provisioning succeeds, or to failed or rejected. When provisioning refuses a bank beneficiary for a precise cause, the response carries that cause in failure.code rather than a generic provider error: A provisioning refusal with no precise cause maps to the generic providerError and the account remains retryable.

SWIFT-supported destination countries

IBAN and Canadian bank registrations are screened at create time against the list of countries OMS can pay out to over SWIFT. If the destination country (derived from the IBAN, an explicit countryCode, or the BIC when neither is available; always Canada for bankCanada) is not on that list, the create returns 201 with status: rejected and failure.code: countryNotSupported, and no provider call is made. bankUs, walletExternal, and card registrations are not screened this way.

Duplicate submissions

POST /external-accounts and card registration deduplicate by owner. A duplicate registration for the same owner returns 409 externalAccountAlreadyRegistered; a registration of the same instrument under a different owner of the same customer usually returns a new 201 with a distinct ext_ ID. On some projects a bankUs account is unique per customer across all of that customer’s owners instead. For walletExternal and bankUs duplicates the 409 body carries a details object that identifies the existing record. This error carries its code as a string, not a number:
matchedOn is blockchainAddressNetworkFamilyOwner for a wallet or routingNumberAccountNumberCustomer for a bank account; tolerate values you do not recognize. existingAccountStatus is active or pending; retrying does not speed up a pending account, which OMS resolves on its own. Registering an account that is failed or rejected again retries it under its existing ext_ ID, returns 201, and adopts the resubmitted label and metadata. Card duplicates return the same 409 externalAccountAlreadyRegistered code with no details object, because the card provider’s dedupe is global and OMS cannot name a specific account. POST /external-accounts requires the Idempotency-Key header and enforces replay: an identical retry with the same key returns the original response. For card registration, the browser SDK sets the key for you.

Response

Sensitive fields are write-only. Full account numbers, IBANs, card numbers, and CVVs are never stored on reads or echoed back; the response carries only their last-four renderings (accountNumberLast4, ibanLast4, and last4 for cards). The type-specific values are in a single details object; the keys present depend on type, and a value OMS does not hold is left out. For bankUs, details.accountType is always present on reads: checking when it was omitted at create time, otherwise the value you supplied. On bank accounts, details.holderName is the counterparty’s name on a counterparty’s account and the customer’s name on the customer’s own.
The details keys for each type: A counterparty-owned wallet response:
asset is usd on bank accounts and cards and is left out on wallets. supportedDestinations lists where the account can be paid, computed per account:
  • A US bank account lists each rail it can receive on (ach, achSameDay, wire, rtp, instant, or intraBank), narrowed by what your project and the platform enable, with minimumAmount and maximumAmount when limits are published for that rail. default: true marks the rail to pre-select in your UI; OMS never picks a rail for you, so still name it on every request. An instant entry carries defaultInstantRail, and an intraBank entry carries the same-bank rail in intraBankRail.
  • An instant destination on a US bank account also reports its remaining daily allowance: availableAmount is the most this project can send on the rail right now, the lower of the per-send maximum and the remaining shared daily allowance rounded down to a configured step, and limitResetsAt is when the allowance next resets. Both are absent when no daily allowance applies. Read them when rendering a send form on an instant rail so the customer sees the live cap rather than only the per-send maximum.
  • A wallet lists each asset and network its vendor offers as a payout destination.
  • IBAN and Canadian bank accounts and cards leave the field out.
A US bank account also lists unavailableDestinations: rails your project has turned on that this account cannot be paid over, each with an asset, a network, and a reason (notOnInstantRail, notWhitelisted, or useIntraBank). A rail your project has not turned on is not listed.

Owner reference

Every external account carries a customer reference to the customer it is registered for, including accounts that one of the customer’s counterparties owns:
When the account is not the customer’s own, owner identifies who owns it: kind (counterparty, or customer for another customer’s account), id (ctp_ or cst_ prefix), and, for a counterparty, its name. owner is left out when the account is the customer’s own. See the Customer reference shared model.

Released sender-attribution holds

When you register a walletExternal account whose address matches inbound transfers held for sender attribution (the address and network in the transaction’s hold.match), the registration submits those transactions for release. Attribution is asynchronous; each transaction moves from awaitingAction.awaitingSenderAttribution to processing once the provider confirms settlement, so an immediate GET on a held transaction may still show awaitingAction. Track the change with GET /transactions/{transactionId} or the transaction.statusChanged webhook.

Managing external accounts

  • GET /external-accounts lists external accounts in the project. customerId, counterpartyId, and status are optional filters; omit them all to list every non-deleted account in the project. status=deleted explicitly lists soft-deleted rows. Paginate with limit (default 50, maximum 100), startingAfter, and endingBefore, passing a page’s nextCursor or previousCursor back unchanged.
  • GET /external-accounts/{externalAccountId} fetches a single account by ID.
  • PATCH /external-accounts/{externalAccountId} updates label and metadata only. Financial and identity fields are immutable; to change a destination, register a new account and re-point to it. Any other key in the body is rejected with 400.
  • DELETE /external-accounts/{externalAccountId} soft-deletes the account and returns 204. While a converting send to the account (a crypto send that swaps to another asset, then sends to this account) still owes a send to it, the delete returns 409 ConvertingSendInFlight and deletes nothing; the error’s cause names the oldest such transaction by its txn_ ID. A retry of the delete succeeds once that transaction completes, its automatic retries finish, or operations close it.

Emergency revoke

To cut off a compromised account while a converting send is in flight, send DELETE /external-accounts/{externalAccountId}?emergencyRevoke=true&reason=.... The reason is required: 3 to 500 characters after trimming, with no personal data (for example, wallet reported compromised). The account is deleted in every case, and the response is 200 with two lists of txn_ IDs:
  • revokedTransactionIds: converting sends whose send had not been issued, which the revoke stopped. Nothing is sent to the account and nothing is returned automatically; each transaction reads failed, with its funds held for operations review.
  • sendsNotRecalledTransactionIds: sends that may already have been issued and may still complete.
Both lists cover only some sends, so an empty sendsNotRecalledTransactionIds does not mean nothing can still reach the account. To find other sends, list the customer’s pending and processing transactions with GET /transactions and check those whose destination is walletExternal with this account’s id.

Statuses

When status is failed, rejected, or invalid, the account carries a failure object: a code, a fixed message, and retryable, which tells you whether trying the same thing again can succeed.

Invalid external accounts

When a payout to an active external account is rejected with a confirmed rail-specific return code, OMS transitions the account to status: invalid and sets failure.code to one of the invalid-account reasons below. The transition fires an externalAccount.statusChanged webhook, and every active virtual account or deposit address that references the invalidated account flips to inactiveActionRequired and stops routing new payouts to that destination. When a bank return made the account invalid, failure.bankCode carries the bank’s own return code (for example, a NACHA return code such as R15 on a US bank ACH payout). Use failure.code to decide what to do; use failure.bankCode when you need the exact return code for support or reconciliation. The identifiers on an external account are immutable; there is no update path that can repair an invalid account. Register a new external account with the corrected details and re-point any dependent virtual accounts or deposit addresses to it to recover. Wire and SWIFT rails do not mark an account invalid; a wire payout failure surfaces on the transaction’s failure, not on the destination external account.

Webhook events

Counterparties

A counterparty is a saved third-party payee in a customer’s address book: a person or business the customer pays or receives from. Bank accounts and wallets that belong to the counterparty are registered as external accounts with owner: { "kind": "counterparty", "counterpartyId": "ctp_..." }. POST /counterparties takes a customerId and an entityType that selects the name fields:
The response adds a read-only name: businessName for a business, or firstName and lastName joined by a space for an individual. It is the same string that appears as owner.name on the counterparty’s accounts. GET /counterparties lists counterparties, optionally filtered by customerId. PATCH /counterparties/{counterpartyId} updates the name fields that match the stored entityType and the contact fields; an empty update returns 422 EmptyUpdate, and address changes are screened again. DELETE /counterparties/{counterpartyId} soft-deletes the counterparty and returns 409 while it still owns active or pending external accounts. Counterparties fire counterparty.created, counterparty.statusChanged, and counterparty.updated.