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, RTP)	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": "walletOms",
    "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, wire, or rtp. 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`), `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:

{
  "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"
}

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 a payout return).
`failed`	Provisioning failed or the provider rejected the account; `failureReason` identifies the cause.
`deleted`	Soft-deleted.

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

​Released sender-attribution holds

​Managing external accounts

​Statuses

​Related