External accounts - Polygon Developer Docs

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

Each external account carries a type-specific ID prefix. The prefix tells you which instrument type to select on the quote side.

ID prefix	Type	Role on a quote
`ext_bankUs_`	US bank account (ACH, same-day ACH, wire)	Destination
`ext_bankIban_`	IBAN bank account (international, SWIFT)	Destination
`ext_bankCa_`	Canadian bank account	Destination
`ext_wlt_`	External wallet (held outside OMS)	Destination
`ext_card_`	Debit card	Source or destination

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

{
  "customerId": "cst_...",
  "source": {
    "type": "walletCrypto",
    "details": { "id": "wlt_...", "asset": "usdc", "network": "polygon" },
    "amount": "500.00"
  },
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "ext_bankUs_...",
      "asset": "usd",
      "network": "ach",
      "accountHolder": "customer"
    }
  }
}

The US bank network is one of ach, achSameDay, or wire. The accountHolder field is always customer. IBAN (bankIban) and Canadian (bankCanada) destinations follow the same pattern with their respective ext_ IDs.

External wallet destination

{
  "destination": {
    "type": "walletExternal",
    "details": { "id": "ext_wlt_...", "asset": "usdc", "network": "polygon" }
  }
}

For an external wallet on a quote you supply exactly one of id (a registered external account, ext_wlt_ prefix) or blockchainAddress (a raw on-chain address).

Card source or destination

{
  "source": {
    "type": "card",
    "details": { "id": "ext_card_...", "asset": "usd" },
    "amount": "100.00"
  }
}

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 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.

{
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "bankUs",
  "bankUs": {
    "accountNumber": "123456789012",
    "routingNumber": "021000021",
    "accountType": "checking",
    "bankName": "Chase"
  },
  "label": "Primary checking"
}

{
  "owner": { "kind": "counterparty", "counterpartyId": "ctp_..." },
  "type": "bankIban",
  "bankIban": {
    "iban": "DE89370400440532013000",
    "BIC": "COBADEFFXXX"
  }
}

{
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "bankCanada",
  "bankCanada": {
    "institutionNumber": "003",
    "transitNumber": "12345",
    "accountNumber": "1234567"
  }
}

{
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "card",
  "card": {
    "cardNumber": "4111111111111111",
    "cvv": "123",
    "expiryMonth": 4,
    "expiryYear": 2028,
    "cardProvider": "visa",
    "billingAddress": {
      "addressLine1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "country": "US"
    }
  }
}

{
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "walletExternal",
  "walletExternal": {
    "blockchainAddress": "0xabc123...",
    "networkFamily": "evm",
    "custodian": "COINBASE_US"
  }
}

Per-type required and optional fields:

Type	Required	Optional
`bankUs`	`accountNumber`, `routingNumber` (nine-digit ABA)	`accountType` (`checking` or `savings`, defaults to `checking` when omitted), `bankName`
`bankIban`	`iban`, `BIC` (8 or 11 characters)	`countryCode` (derived from the IBAN’s first two letters when omitted), `bankAddress`
`bankCanada`	`institutionNumber` (three digits), `transitNumber` (five digits), `accountNumber`	`bankName`
`card`	`cardNumber`, `cvv`, `expiryMonth` (integer), `expiryYear` (integer), `billingAddress`	`cardProvider` (`visa`, `mastercard`, `amex`, or `discover`), `webSessionId` (fraud-screening session ID)
`walletExternal`	`blockchainAddress`, `networkFamily` (`evm` or `solana`), `custodian`	`otherCustodian` (required when `custodian` is `OTHER`)

An external wallet is registered per network family: an EVM address registered once is valid across every EVM chain. See Debit cards for the card-specific details. Provisioning runs synchronously against the configured payment provider: the account starts pending and flips to active or failed.

SWIFT-supported destination countries

IBAN 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) is not on that list, the create returns 201 with status: rejected and rejectionReason: countryNotSupported, and no vendor call is made. bankUs, walletExternal, and card registrations are not screened this way.

Duplicate submissions

POST /external-accounts and POST /external-accounts/cards 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 returns a new 201 with a distinct ext_ ID. For wallet and bank duplicates the 409 body carries a details object that identifies the existing record:

{
  "error": "externalAccountAlreadyRegistered",
  "code": "externalAccountAlreadyRegistered",
  "details": {
    "existingAccountId": "ext_wlt_...",
    "existingAccountStatus": "active",
    "matchedOn": ["blockchainAddress", "networkFamily"]
  }
}

existingAccountStatus is the current status of the surviving record. active and pending both return 409, so a client cannot use retry to force a re-drive of a pending row: recovery from a stuck pending runs asynchronously through the stale-pending sweeper. failed and rejected rows are transparently re-driven under their existing ext_ ID and adopt 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. Both create routes require the Idempotency-Key header and enforce replay: an identical retry with the same key returns the original response.

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, cardNumberLast4). Exactly one per-type response object is populated, selected by type. For bankUs, accountType is always present on reads: checking when it was omitted at create time, otherwise the value you supplied.

{
  "id": "ext_bankUs_...",
  "object": "externalAccount",
  "owner": { "kind": "customer", "customerId": "cst_..." },
  "type": "bankUs",
  "category": "fiatAccount",
  "status": "pending",
  "bankUs": {
    "accountNumberLast4": "9012",
    "routingNumber": "021000021",
    "accountType": "checking",
    "bankName": "Chase"
  },
  "label": "Primary checking",
  "createdAt": "2026-07-07T10:30:00Z",
  "updatedAt": "2026-07-07T10:30:00Z"
}

Owner rendering

External account responses carry ownerDisplayName, an opaque, ready-to-render label for the owner (for example, the customer’s or counterparty’s name). Customer-owned accounts additionally carry a customer summary:

"ownerDisplayName": "Jane Doe",
"customer": { "id": "cst_...", "name": "Jane Doe" }

customer is populated on GET /external-accounts, GET /external-accounts/{externalAccountId}, and PATCH /external-accounts/{externalAccountId} responses for customer-owned accounts. Counterparty-owned accounts populate ownerDisplayName from the counterparty and omit customer. See Customer summary on a transaction for the shared shape.

Released sender-attribution holds

When you register a walletExternal account whose address matches inbound transfers held for sender attribution, the create response includes resolvedTransactions: the IDs of the transactions the registration submitted for release. Attribution is asynchronous; each transaction moves from awaitingAction.awaitingSenderAttribution to processing once the provider confirms settlement, so an immediate GET on one of the IDs may still show awaitingAction. The field appears only on the POST create response, never on reads.

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, startingAfter, and endingBefore.
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.

Statuses

Status	Meaning
`pending`	Submitted to the provider; provisioning in progress.
`active`	Usable on quotes.
`rejected`	Refused at create time; `rejectionReason` identifies the cause (for example, a country prohibited by compliance screening, or an international destination whose country is outside OMS’s SWIFT coverage, `countryNotSupported`).
`invalid`	Became unusable after activation (for example, following an ACH payout return). `invalidReason` identifies the cause; see Invalid external accounts.
`failed`	Provisioning failed or the provider rejected the account; `failureReason` identifies the cause.
`deleted`	Soft-deleted.

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 stamps a closed-enum invalidReason on it. The transition fires an externalAccount.statusChanged webhook, and every active virtual account or deposit address that references the invalidated account flips to inactiveActionRequired so it can no longer route new payouts to a known-bad destination.

`invalidReason`	Meaning
`accountClosed`	The receiving bank reported the account closed.
`accountFrozenByBank`	The receiving bank reported the account frozen.
`routingOrAccountNumberInvalid`	The routing or account number was rejected as invalid.
`accountHolderDeceased`	The receiving bank reported the account holder deceased.
`accountDoesNotSupportTransfers`	The receiving account cannot accept the requested transfer type.
`payeeNameMismatch`	The payee name on the payout did not match the account holder on file.
`walletUnreachableOnNetwork`	An on-chain destination was reported unreachable on the target network.
`billingAddressMismatch`	The card issuer rejected the transaction on billing-address verification.
`cardExpired`	The card is past its expiration date.
`cardClosedOrLostStolen`	The card issuer reported the card closed, lost, or stolen.
`pushToCardUnsupported`	The card does not support push-to-card payouts.
`cardDeclinedByIssuer`	The card issuer declined the payout.

The account also carries an invalidReasonCode field with the provider’s own code for the underlying failure (for example, a NACHA return code such as R15 on a US bank ACH payout). Use invalidReason to decide what to do; use invalidReasonCode when you need the exact provider 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 currently populate invalidReason; a wire payout failure surfaces on the transaction itself, not on the destination external account.

Debit cards: using a card as a funding source or payout destination
Bank transfers guide: ACH and wire transfer walkthrough
Transactions: how to use an external account on a quote

​Supported types

​Referencing an external account in a transaction

​US bank destination

​External wallet destination

​Card source or destination

​Registering external accounts

​SWIFT-supported destination countries

​Duplicate submissions

​Response

​Owner rendering

​Released sender-attribution holds

​Managing external accounts

​Statuses

​Invalid external accounts

​Related