> ## Documentation Index > Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt > Use this file to discover all available pages before exploring further. # Create an External Account > Create an External Account (saved payment destination). Provisions synchronously against the configured payment provider; the account starts `pending` and flips to `active` or `failed`. Exactly one per-type detail object must match `type`. The owner discriminator determines whether this account belongs to a customer directly or to one of the customer's counterparties. ## OpenAPI ````yaml /api-reference/openapi.yaml post /external-accounts openapi: 3.0.3 info: title: Polygon OMS Public API version: v26.05.28-0001 description: >- Unified API for moving money between crypto and fiat. Three ways to move money: Transactions (instant, wallet or card funded, including Cash-In for in-person cash deposits), Deposit Addresses (reusable crypto deposit configurations), and Virtual Accounts (dedicated bank accounts that auto-convert fiat to crypto). Standard transactions follow a two-step flow: create a Quote (pricing), then create a Transaction (execution). Cash-in codes generate a one-time deposit code for in-person cash deposits at retail locations. contact: name: Polygon OMS url: https://oms.polygon.technology servers: - url: https://sandbox-api.polygon.technology/v0.10 description: Sandbox - url: https://api.polygon.technology/v0.10 description: Production security: - BearerAuth: [] tags: - name: Auth description: Authentication via FrontEgg - name: Customers description: Customer management and KYC - name: Customer - name: Wallet - name: Quote - name: Transaction - name: Webhook - name: CashIns - name: CashLocation - name: Sandbox - name: VirtualAccount - name: Counterparty - name: ExternalAccount - name: DepositAddress - name: Simulation paths: /external-accounts: post: tags: - ExternalAccount summary: Create an External Account description: >- Create an External Account (saved payment destination). Provisions synchronously against the configured payment provider; the account starts `pending` and flips to `active` or `failed`. Exactly one per-type detail object must match `type`. The owner discriminator determines whether this account belongs to a customer directly or to one of the customer's counterparties. operationId: createExternalAccount parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/ExternalAccountCreateRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ExternalAccount' description: >- The request has succeeded and a new resource has been created as a result. components: parameters: IdempotencyKeyHeader: description: >- Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID. in: header name: Idempotency-Key required: true schema: type: string schemas: ExternalAccountCreateRequest: description: |- Create an External Account. Exactly one per-type detail object must be supplied, matching `type`; the service validates the correct subset and rejects mismatches with 422. properties: bankCanada: allOf: - $ref: '#/components/schemas/ExternalAccountBankCanadaRequest' description: Required when `type = bankCanada`. bankIban: allOf: - $ref: '#/components/schemas/ExternalAccountBankIbanRequest' description: Required when `type = bankIban`. bankUs: allOf: - $ref: '#/components/schemas/ExternalAccountBankUsRequest' description: Required when `type = bankUs`. card: allOf: - $ref: '#/components/schemas/ExternalAccountCardRequest' description: Required when `type = card`. label: type: string metadata: type: object additionalProperties: type: string owner: $ref: '#/components/schemas/ExternalAccountOwner' type: $ref: '#/components/schemas/ExternalAccountType' walletExternal: allOf: - $ref: '#/components/schemas/ExternalAccountWalletExternalRequest' description: Required when `type = walletExternal`. required: - owner - type type: object ExternalAccount: description: |- A saved payment destination registered for a customer or one of their counterparties. Exactly one of the per-type response detail objects is populated, selected by `type`. Write-only secrets (full account number, full IBAN) are never present on reads - only their last-4 renderings. properties: bankCanada: allOf: - $ref: '#/components/schemas/ExternalAccountBankCanadaResponse' description: Populated when `type = bankCanada`. bankIban: allOf: - $ref: '#/components/schemas/ExternalAccountBankIbanResponse' description: Populated when `type = bankIban`. bankUs: allOf: - $ref: '#/components/schemas/ExternalAccountBankUsResponse' description: Populated when `type = bankUs`. card: allOf: - $ref: '#/components/schemas/ExternalAccountCardResponse' description: Populated when `type = card`. category: $ref: '#/components/schemas/ExternalAccountCategory' createdAt: type: string format: date-time failureReason: allOf: - $ref: '#/components/schemas/ExternalAccountFailureReason' description: Set when `status = failed`. id: type: string label: type: string metadata: type: object additionalProperties: type: string object: enum: - externalAccount type: string owner: $ref: '#/components/schemas/ExternalAccountOwner' rejectionReason: description: Set when status = `rejected` (compliance screening). type: string resolvedTransactions: description: >- Transaction ids that this registration submitted for sender-attribution release. Returned ONLY on the POST create response, and only when registering this walletExternal matched held inbounds. Attribution is async: each entry is submitted to the provider from `awaitingAction.awaitingSenderAttribution` and moves to `processing.fundsPulled` once settlement confirms, so an immediate GET of an id may still show `awaitingAction`. Omitted on GETs (the create path is the only writer). items: type: string type: array status: $ref: '#/components/schemas/ExternalAccountStatus' type: $ref: '#/components/schemas/ExternalAccountType' updatedAt: type: string format: date-time walletExternal: allOf: - $ref: '#/components/schemas/ExternalAccountWalletExternalResponse' description: Populated when `type = walletExternal`. type: object ExternalAccountBankCanadaRequest: description: bankCanada create detail. properties: accountNumber: description: >- Canadian bank account number (7-12 digits). Write-only; never returned (reads expose `accountNumberLast4`). type: string bankName: type: string institutionNumber: description: Three-digit institution number. type: string transitNumber: description: Five-digit transit number. type: string required: - institutionNumber - transitNumber - accountNumber type: object ExternalAccountBankIbanRequest: description: bankIban create detail. properties: BIC: description: SWIFT BIC (8 or 11 chars). type: string bankAddress: type: string countryCode: description: >- ISO 3166-1 alpha-2. Optional - derived from the IBAN's first two letters when omitted; validated against any supplied value. type: string iban: description: |- IBAN value. Write-only; never returned (reads expose `ibanLast4`). Shape `^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$`. type: string required: - iban - BIC type: object ExternalAccountBankUsRequest: description: bankUs create detail. properties: accountNumber: description: |- US bank account number. Write-only; never returned (reads expose `accountNumberLast4`). type: string accountType: $ref: '#/components/schemas/BankAccountType' bankName: type: string routingNumber: description: Nine-digit ABA routing number. type: string required: - accountNumber - routingNumber type: object ExternalAccountCardRequest: description: >- card create detail. INTERIM (no VGS): `cardNumber`/`cvv` are raw PAN/CVV, write-only, never returned or stored - only last4/brand/expiry persist. The same fields carry a VGS alias once VGS lands (no shape change). properties: billingAddress: allOf: - $ref: '#/components/schemas/ExternalAccountCardBillingAddress' description: >- Card billing address (issuer AVS / fraud). Required for card vaulting. cardNumber: description: Write-only. Raw PAN (interim) or VGS alias (later). Never returned. type: string cardProvider: $ref: '#/components/schemas/CardBrand' cvv: description: Write-only. Never returned. type: string expiryMonth: format: int32 type: integer expiryYear: format: int32 type: integer webSessionId: description: >- Fraud-screening web session identifier, forwarded to the card processor. type: string required: - cardNumber - cvv - expiryMonth - expiryYear - billingAddress type: object ExternalAccountOwner: description: Who owns the External Account. discriminator: mapping: counterparty: $ref: '#/components/schemas/OwnerCounterparty' customer: $ref: '#/components/schemas/OwnerCustomer' propertyName: kind oneOf: - $ref: '#/components/schemas/OwnerCustomer' - $ref: '#/components/schemas/OwnerCounterparty' type: object ExternalAccountType: description: >- External Account type. Selects which per-type detail object the request must carry. enum: - bankUs - bankIban - bankCanada - card - walletExternal type: string ExternalAccountWalletExternalRequest: description: >- walletExternal create detail. The address is stored as submitted and matched exactly; the service normalizes it (EVM lowercased, Solana raw) for the upsert key. properties: blockchainAddress: description: Blockchain wallet address. type: string custodian: allOf: - $ref: '#/components/schemas/DestinationCustodian' description: DestinationCustodian enum value (reused from VA). networkFamily: $ref: '#/components/schemas/NetworkFamily' otherCustodian: description: Required iff `custodian = OTHER`; max 100 chars. type: string required: - blockchainAddress - networkFamily - custodian type: object ExternalAccountBankCanadaResponse: description: >- bankCanada response detail. The full account number is never echoed - only its last four digits. properties: accountNumberLast4: description: Last four digits of the Canadian bank account number. type: string bankName: type: string institutionNumber: description: Three-digit institution number. type: string transitNumber: description: Five-digit transit number. type: string required: - institutionNumber - transitNumber - accountNumberLast4 type: object ExternalAccountBankIbanResponse: description: |- bankIban response detail. The full IBAN is never echoed - only its last four characters. properties: BIC: description: SWIFT BIC (8 or 11 chars). type: string bankAddress: type: string countryCode: description: ISO 3166-1 alpha-2; derived from the IBAN prefix when not supplied. type: string ibanLast4: description: Last four characters of the IBAN. type: string required: - ibanLast4 - BIC - countryCode type: object ExternalAccountBankUsResponse: description: >- bankUs response detail. The full account number is never echoed - only its last four digits. properties: accountNumberLast4: description: Last four digits of the US bank account number. type: string accountType: $ref: '#/components/schemas/BankAccountType' bankName: type: string routingNumber: description: Nine-digit ABA routing number (not a secret). type: string required: - accountNumberLast4 - routingNumber type: object ExternalAccountCardResponse: description: |- card response detail. Last-4 + expiry only; PAN/CVV are never stored or returned. properties: cardNumberLast4: description: Last four digits of the card PAN. type: string cardProvider: $ref: '#/components/schemas/CardBrand' expiryMonth: format: int32 type: integer expiryYear: format: int32 type: integer type: object ExternalAccountCategory: description: Coarse classification derived from `type`, stored for query convenience. enum: - fiatAccount - crypto type: string ExternalAccountFailureReason: description: Closed enum stamped on an External Account when `status = failed`. enum: - ereborRejected - cardProviderRejected - providerAccountMissing - cardLimitReached - cardInUse - provisioningTimeout - systemError type: string ExternalAccountStatus: description: >- Lifecycle of an External Account. `pending → active` on successful provisioning; `pending → failed` on upstream rejection or provisioning timeout. `rejected` (create-time country screening) and `invalid` (derived from payout returns) are reserved enum values with no transition logic in this slice. `deleted` is the soft-delete terminal. enum: - active - pending - rejected - invalid - deleted - failed type: string ExternalAccountWalletExternalResponse: description: >- walletExternal response detail. The blockchain address is public, so it is echoed as submitted. properties: blockchainAddress: description: The registered blockchain address, as submitted. type: string custodian: allOf: - $ref: '#/components/schemas/DestinationCustodian' description: DestinationCustodian enum value (reused from VA). networkFamily: $ref: '#/components/schemas/NetworkFamily' otherCustodian: description: Set when `custodian = OTHER`. type: string required: - blockchainAddress - networkFamily - custodian type: object BankAccountType: description: Bank account sub-type for US accounts. enum: - checking - savings type: string ExternalAccountCardBillingAddress: description: >- Card billing address: the address the card issuer has on file for the payment instrument, used for issuer AVS / fraud screening. This is a property of the card, NOT the customer's KYC identity (a customer may vault cards with differing billing addresses), so it is supplied per card by the partner and is never derived from the customer record. Forwarded to the card vault; only card_last4 is persisted. properties: addressLine1: type: string addressLine2: type: string city: type: string country: description: ISO 3166-1 alpha-2 country code. type: string firstName: description: Cardholder first name on the issuer's billing record. type: string lastName: description: Cardholder last name on the issuer's billing record. type: string state: description: State / region code (2-letter for US). type: string zipCode: type: string required: - addressLine1 - city - state - country - zipCode type: object CardBrand: description: Card network/brand. enum: - visa - mastercard - amex - discover type: string OwnerCounterparty: description: Counterparty-owned External Account (an address-book entry). properties: counterpartyId: description: Counterparty (ctp_…) id. type: string kind: enum: - counterparty type: string required: - kind - counterpartyId type: object OwnerCustomer: description: Customer-owned External Account. properties: customerId: description: Owning customer (cus_… or legacy public id). type: string kind: enum: - customer type: string required: - kind - customerId type: object DestinationCustodian: enum: - ANCHORAGE_SG - ANCHORAGE_US - AQUANOW_CA - B2C2_UK - B2C2_US - BITGO_SG - BITGO_US - BITSTAMP_US - BVNK_US - CIRCLE_FR - CIRCLE_US - CITIBANK_US - COINBASE_US - COINSMART_CA - COPPER_CH - COPPER_UK - CUMBERLAND_DRW_LLC_US - CUMBERLAND_SG - EREBOR_BANK_US - FALCONX_US - FIDELITY_UK - FIDELITY_US - FIREBLOCKS_APAC - FIREBLOCKS_US - GALAXY_KY - GEMINI_US - KRAKEN_BVI - KRAKEN_EU_IE - KRAKEN_UK - KRAKEN_US - NUBANK_BR - PAXOS_US - RAMP_NETWORK_US - ROBINHOOD_US - WINTERMUTE_GB - SELF_HOSTED - OTHER type: string NetworkFamily: description: >- Crypto network family for a registered external wallet. A walletExternal is registered per family (an EVM address is valid across every EVM chain); the service provisions one counterparty blockchain address per served network in the family. enum: - evm - solana type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token from POST /auth/token ````