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.

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 a customer’s external accounts. customerId is required; counterpartyId optionally narrows the list to one counterparty’s accounts. 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`	Failed create-time compliance screening; `rejectionReason` identifies the cause.
`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 bank payout to an active US bank external account returns with a confirmed NACHA 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.
`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.

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

​Response

​Owner rendering

​Released sender-attribution holds

​Managing external accounts

​Statuses

​Invalid external accounts

​Related