> ## 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. # Update a Virtual Account > Update a Virtual Account. Patchable fields: `destination` (re-point), `sponsorGas`, `label`, `metadata`; any other JSON key is rejected with 400. Re-pointing `destination` to a healthy External Account recovers a VA from `inactiveActionRequired` back to `active`. ## OpenAPI ````yaml /api-reference/openapi.yaml patch /virtual-accounts/{virtualAccountId} 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.12 description: Sandbox - url: https://api.polygon.technology/v0.12 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: CashIns - name: CashLocation - name: Sandbox - name: VirtualAccount - name: Counterparty - name: ExternalAccount - name: Reference - name: DepositAddress paths: /virtual-accounts/{virtualAccountId}: patch: tags: - VirtualAccount summary: Update a Virtual Account description: |- Update a Virtual Account. Patchable fields: `destination` (re-point), `sponsorGas`, `label`, `metadata`; any other JSON key is rejected with 400. Re-pointing `destination` to a healthy External Account recovers a VA from `inactiveActionRequired` back to `active`. operationId: updateVirtualAccount parameters: - name: virtualAccountId in: path required: true description: Virtual Account ID (`va_` prefix). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VirtualAccountUpdateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/VirtualAccount' components: schemas: VirtualAccountUpdateRequest: type: object properties: destination: allOf: - $ref: '#/components/schemas/VirtualAccountDestinationRequest' description: >- Re-point the VA destination (walletExternal by registered EA id, a bank EA, or a walletFiat fiat wallet — same kind as the current destination: a cross-kind switch involving walletFiat is rejected with 422 `destinationTypeSwitchNotSupported`). Re-validated exactly like create; walletCrypto is NOT currently supported — 422 destinationWalletCryptoNotSupported. returnDestination: allOf: - $ref: '#/components/schemas/FiatReturnDestination' description: >- Re-point or clear the fiat return destination (v0.11-8). Re-validated exactly like create; an explicit `null` in the JSON body clears a previously set return destination. sponsorGas: type: boolean description: |- When `true`, OMS absorbs the on-chain gas cost for the destination delivery. Only `true` is currently supported; accepted for forward-compatibility. default: true label: type: string description: Partner display label. metadata: type: object additionalProperties: type: string description: >- Free-form key-value pairs stored on the resource and echoed back on reads. description: >- Partial update payload for a Virtual Account. The patchable fields are `destination` (re-point to a different walletExternal or bank target), `returnDestination` (re-point or clear the fiat return destination), `sponsorGas`, `label`, and `metadata`. Any additional key in the JSON body is rejected with 400 by the handler (strict whitelist). Re-pointing `destination` to a healthy External Account recovers a VA from `inactiveActionRequired` back to `active`; a re-point on an already `active` VA updates the target without a status transition. VirtualAccount: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Virtual Account ID (`va_` prefix). object: type: string enum: - virtualAccount description: Resource type discriminator. Always "virtualAccount". customerId: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer that owns this record (`cst_` prefix). customer: allOf: - $ref: '#/components/schemas/CustomerSummary' description: |- Resolved id + display name of the owning customer, so list/detail rendering needs no follow-up customer fetch (v0.12, #2665). status: allOf: - $ref: '#/components/schemas/VirtualAccountStatus' description: Current lifecycle status of the virtual account. sourceToDestination: allOf: - $ref: '#/components/schemas/SourceToDestination' description: >- Corridor composite derived from the destination type — `fiatAccountToCrypto` for a crypto-wallet destination (inbound fiat auto-converts), or `fiatAccountToFiatAccount` for a bank or walletFiat destination (inbound USD forwarded onward — the same token for both; walletFiat introduces no new corridor). statusReason: type: string description: Human-readable explanation of the current status. source: allOf: - $ref: '#/components/schemas/VirtualAccountSource' description: Expected inbound rail detail. depositInstructions: allOf: - $ref: '#/components/schemas/VirtualAccountInstructions' description: Null until Erebor provisions the DDA (DEPOSIT_ACCOUNT.OPEN). destination: allOf: - $ref: '#/components/schemas/TransactionSide' description: 'V0.10: unified side shape.' returnDestination: allOf: - $ref: '#/components/schemas/FiatReturnDestination' description: >- The configured fiat return destination (v0.11-8) for failed outbound legs; absent/null when none is set (the project return policy applies instead, once T13 wires the waterfall). sponsorGas: type: boolean description: >- Whether OMS absorbs the on-chain gas cost for the destination delivery. Persisted from the create/update request (currently only `true` is accepted). bankMemo: type: string description: Wire/ACH memo the customer can include with deposits. label: type: string description: Partner display label. metadata: type: object additionalProperties: type: string description: Free-form key-value pairs supplied at creation or update. createdAt: type: string format: date-time description: When the virtual account was created. updatedAt: type: string format: date-time description: When the virtual account was last updated. failureReason: allOf: - $ref: '#/components/schemas/VirtualAccountFailureReason' description: >- Set when status = `failed`; closed enum identifying the failure category. deletionRequestedAt: type: string format: date-time description: >- Set when DELETE has been requested but the close webhook has not yet finalized. deletionRequestedBy: type: string description: Identity (JWT subject claim) of the caller who invoked DELETE. finalBalance: allOf: - $ref: '#/components/schemas/AmountObject' description: DDA balance snapshot at the moment the VA flipped to `deleted`. description: >- A dedicated bank account number issued for a customer. Inbound fiat deposits are automatically converted and delivered to the configured destination, creating a transaction per deposit. VirtualAccountDestinationRequest: type: object oneOf: - $ref: '#/components/schemas/BankUsSideRequest' - $ref: '#/components/schemas/BankIbanSideRequest' - $ref: '#/components/schemas/BankCanadaSideRequest' - $ref: '#/components/schemas/WalletCryptoSideRequest' - $ref: '#/components/schemas/WalletExternalRegisteredSideRequest' - $ref: '#/components/schemas/WalletFiatDestinationRequest' discriminator: propertyName: type mapping: bankUs: $ref: '#/components/schemas/BankUsSideRequest' bankIban: $ref: '#/components/schemas/BankIbanSideRequest' bankCanada: $ref: '#/components/schemas/BankCanadaSideRequest' walletCrypto: $ref: '#/components/schemas/WalletCryptoSideRequest' walletExternal: $ref: '#/components/schemas/WalletExternalRegisteredSideRequest' walletFiat: $ref: '#/components/schemas/WalletFiatDestinationRequest' description: >- Where the Virtual Account delivers the deposited value, on the shared discriminated side shape (same shapes as Deposit Addresses). Crypto arms auto-convert the inbound fiat to crypto (`fiatAccountToCrypto`): `walletExternal` delivers to a registered External Account (ext_ id). Unlike Cash-In, Virtual Accounts require the external wallet to be registered — raw unregistered addresses are not allowed. `walletCrypto` is declared but NOT currently supported: it is rejected with 422 `destinationWalletCryptoNotSupported` — use `walletExternal` for externally-held wallets. (Planned to return for non-custodial wallets in v0.12.) Bank arms (`bankUs` / `bankIban` / `bankCanada`) auto-forward the inbound USD onward to a registered bank-type External Account (`fiatAccountToFiatAccount`). The `network` enums are carried verbatim from the shared Side models (bankUs: ach|achSameDay|wire; bankIban: swift; bankCanada: swift|local); the 422 filtering of CAD / `local` is applied service-side, not by this contract. The `walletFiat` arm (v0.12) holds the inbound USD as a fiat balance in the customer's own Erebor fiat wallet, credited via an internal book transfer (`fiatAccountToFiatAccount` — the same corridor token as the bank arms; the resolved destination instrument reads `network: bookTransfer`). The wallet must belong to the Virtual Account's customer (422 `walletCustomerMismatch`), be `active` (422 `walletNotActive`), and hold `usd`; the project must have the `book_transfer` outgoing rail enabled (403 `destinationRailNotAllowed`). The reused side arms carry an optional `amount`, which is meaningless for a standing destination — the deposited value determines what is delivered — and is rejected at validation. The server validates the side `details` (asset/network/accountHolder) against the resolved EA/wallet. FiatReturnDestination: type: object oneOf: - $ref: '#/components/schemas/FiatReturnDestinationBankUs' - $ref: '#/components/schemas/FiatReturnDestinationBankIban' - $ref: '#/components/schemas/FiatReturnDestinationBankCanada' - $ref: '#/components/schemas/FiatReturnDestinationWalletFiat' discriminator: propertyName: type mapping: bankUs: $ref: '#/components/schemas/FiatReturnDestinationBankUs' bankIban: $ref: '#/components/schemas/FiatReturnDestinationBankIban' bankCanada: $ref: '#/components/schemas/FiatReturnDestinationBankCanada' walletFiat: $ref: '#/components/schemas/FiatReturnDestinationWalletFiat' description: >- Where inbound fiat is returned when its outbound leg can't be completed (v0.11-8). Pick a `type`: a bank account (`bankUs` / `bankIban` / `bankCanada`, each with a required `network` naming the rail) or a fiat balance wallet (`walletFiat` — no network, internal ledger). Shared by the Virtual Account `returnDestination` and (later) the return policy's `fiat.returnDestinations`. `walletFiat`, and `bankCanada` with a `local` network (CAD), are rejected with 422 `railNotSupported` in v1 — bank rails (USD) only. typeId: type: string pattern: >- ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$ description: >- Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired. x-go-type: string CustomerSummary: type: object required: - id - name properties: id: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer id (`cst_` prefix). name: type: string description: Customer display name. description: >- A minimal, resolved reference to the owning OMS customer — id plus display name, for list/detail rendering without a follow-up customer fetch (v0.12 list enrichment, #2665). Distinct from `Party`: this is always the record's OWNING customer (Transaction.customerId / VirtualAccount.customerId / DepositAddress.customerId), not whichever side a party sits on. VirtualAccountStatus: type: string enum: - pending - active - frozen - closed - deleted - failed - inactiveActionRequired description: >- Lifecycle of a Virtual Account. pending: awaiting bank provisioning. active: accepting deposits. frozen: deposits held by compliance. inactiveActionRequired: destination unusable - re-point `destination` to recover. closed: permanently disabled. deleted: close flow finalized. failed: provisioning failed. SourceToDestination: type: string enum: - cryptoToCrypto - cryptoToCash - cryptoToFiatAccount - cashToCrypto - fiatAccountToCrypto - fiatAccountToFiatAccount description: >- Composite of source and destination instrument categories, inferred from each side. The cash corridors (`cryptoToCash`, `cashToCrypto`) are derived from a cash-pickup destination / cash-in source respectively; the rest map straight from the internal corridor type. VirtualAccountSource: type: object required: - asset - network properties: asset: type: string description: 'Fixed for Alpha: "usd".' network: type: string description: 'Fixed for Alpha: "usBank".' description: >- Expected inbound rail for the virtual account: fiat asset and bank network. VirtualAccountInstructions: type: object properties: bankUs: type: array items: $ref: '#/components/schemas/BankRoutingBlock' description: >- Spec-mandated (v0.11/v0.12) VA deposit-instructions wrapper. bankUs holds zero, one, or two routing blocks (domestic + SWIFT), depending on which incoming rails the partner has enabled. TransactionSide: type: object oneOf: - $ref: '#/components/schemas/WalletCryptoInstrument' - $ref: '#/components/schemas/WalletExternalInstrument' - $ref: '#/components/schemas/WalletFiatInstrument' - $ref: '#/components/schemas/BankUsInstrument' - $ref: '#/components/schemas/BankIbanInstrument' - $ref: '#/components/schemas/BankCanadaInstrument' - $ref: '#/components/schemas/CardInstrument' - $ref: '#/components/schemas/CashInstrument' discriminator: propertyName: type mapping: walletCrypto: $ref: '#/components/schemas/WalletCryptoInstrument' walletExternal: $ref: '#/components/schemas/WalletExternalInstrument' walletFiat: $ref: '#/components/schemas/WalletFiatInstrument' bankUs: $ref: '#/components/schemas/BankUsInstrument' bankIban: $ref: '#/components/schemas/BankIbanInstrument' bankCanada: $ref: '#/components/schemas/BankCanadaInstrument' card: $ref: '#/components/schemas/CardInstrument' cash: $ref: '#/components/schemas/CashInstrument' description: >- The source side of a transaction/quote (v0.10): a typed instrument carrying identity (`party`) and instrument detail. Amounts live only in `pricing`. VirtualAccountFailureReason: type: string enum: - provisioningTimeout - systemError - ereborRejected - deletePendingTimeout description: >- Closed enum stamped by failVA when a VA flips to terminal `failed` state. AmountObject: type: object required: - value - currency - display properties: value: allOf: - $ref: '#/components/schemas/int64String' description: Amount in fiat minor units (e.g. cents). currency: type: string description: ISO 4217 currency code. display: type: string description: Human-readable rendering (e.g. "12.34 USD"). description: >- Single-amount snapshot - value in minor units, plus the currency code and a human-readable display string. Used wherever the API exposes a one-shot amount (e.g. virtualAccount.finalBalance), as distinct from balance shapes with available/pending/reserved components. BankUsSideRequest: type: object required: - type - details properties: type: type: string enum: - bankUs description: Type discriminator. details: $ref: '#/components/schemas/BankUsSideDetails' amount: $ref: '#/components/schemas/decimalString' description: Deliver to a US bank account. title: US bank account BankIbanSideRequest: type: object required: - type - details properties: type: type: string enum: - bankIban description: Type discriminator. details: $ref: '#/components/schemas/BankIbanSideDetails' amount: $ref: '#/components/schemas/decimalString' description: Deliver to an IBAN account over SWIFT (USD). title: IBAN bank account BankCanadaSideRequest: type: object required: - type - details properties: type: type: string enum: - bankCanada description: Type discriminator. details: $ref: '#/components/schemas/BankCanadaSideDetails' amount: $ref: '#/components/schemas/decimalString' description: >- Deliver to a Canadian bank account. USD routes over SWIFT; CAD over local rails. title: Canadian bank account WalletCryptoSideRequest: type: object required: - type - details properties: type: type: string enum: - walletCrypto description: Type discriminator. details: $ref: '#/components/schemas/WalletCryptoSideDetails' amount: $ref: '#/components/schemas/decimalString' description: Pull from / deliver to an OMS Multi-Chain Wallet owned by the customer. title: OMS wallet WalletExternalRegisteredSideRequest: type: object required: - type - details properties: type: type: string enum: - walletExternal description: Type discriminator. details: $ref: '#/components/schemas/WalletExternalRegisteredSideDetails' amount: $ref: '#/components/schemas/decimalString' description: >- Deliver to a wallet held outside OMS, by registered ExternalAccount only (id-only; raw addresses are not accepted). Used by Virtual Account destinations; the raw-address `WalletExternalSideRequest` stays quote/transaction-only. title: External wallet (registered) WalletFiatDestinationRequest: type: object required: - type - details properties: type: type: string enum: - walletFiat description: Type discriminator. details: $ref: '#/components/schemas/WalletFiatSideDetails' description: >- Hold the deposited value as a fiat balance in the customer's fiat wallet (only `usd` today). Credited by an internal book transfer at the partner bank — the resolved destination instrument reads `network: bookTransfer`. The wallet must belong to the route's customer (422 `walletCustomerMismatch`) and be `active` (422 `walletNotActive`). Request shape per the ratified OMS v0.12 `WalletFiatDestination` schema: no `network`, no `amount`. title: Fiat wallet FiatReturnDestinationBankUs: type: object required: - type - network - id properties: type: type: string enum: - bankUs description: Type discriminator. network: type: string enum: - ach - achSameDay - wire description: Rail to return on. id: type: string description: US bank ExternalAccount id (ext_ prefix). description: Registered US bank fiat return destination (v0.11-8). title: US bank account FiatReturnDestinationBankIban: type: object required: - type - network - id properties: type: type: string enum: - bankIban description: Type discriminator. network: type: string enum: - swift id: type: string description: IBAN ExternalAccount id (ext_ prefix). description: Registered IBAN fiat return destination (v0.11-8). title: IBAN bank account FiatReturnDestinationBankCanada: type: object required: - type - network - id properties: type: type: string enum: - bankCanada description: Type discriminator. network: type: string enum: - swift - local description: USD uses swift; CAD uses local (CAD rejected 422 in v1). id: type: string description: Canadian bank ExternalAccount id (ext_ prefix). description: >- Registered Canadian bank fiat return destination (v0.11-8). USD uses `swift`; CAD (`local`) is rejected with 422 in v1 (USD-only). title: Canadian bank account FiatReturnDestinationWalletFiat: type: object required: - type - id properties: type: type: string enum: - walletFiat description: Type discriminator. id: type: string description: OMS fiat wallet id (wlt_fiat_ prefix). Rejected 422 in v1. description: >- Fiat balance wallet return destination (v0.11-8). Rejected with 422 in v1 — holding a return as a fiat balance is planned for v0.12 (mirrors the `walletFiat` VA-destination rejection). title: Fiat wallet BankRoutingBlock: type: object required: - bankName - bankAddress - accountNumber - routingNumber - accountType - BIC - beneficiary - memo properties: supportedSources: type: array items: $ref: '#/components/schemas/AssetNetworkPair' description: Asset/network pairs this routing block accepts deposits for. bankName: type: string bankAddress: type: string accountNumber: type: string routingNumber: type: string nullable: true description: US domestic only; null for SWIFT. accountType: type: string nullable: true description: US domestic only; null for SWIFT. Always "checking" when present. BIC: type: string nullable: true description: SWIFT only; null for US domestic. beneficiary: $ref: '#/components/schemas/BankRoutingBlockBeneficiary' memo: type: string nullable: true description: |- SWIFT only; null for US domestic. OMS-generated: "FFC ". description: >- One bank-routing entry within VirtualAccountInstructions.bankUs. US-domestic fields (routingNumber, accountType) are null on a SWIFT entry; SWIFT-only fields (BIC, memo) are null on a domestic entry. WalletCryptoInstrument: type: object required: - type - category - details - displayName properties: party: allOf: - $ref: '#/components/schemas/Party' description: Structured identity of who is on this side. type: type: string enum: - walletCrypto description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/WalletCryptoDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: OMS-custodied crypto wallet instrument. title: OMS wallet WalletExternalInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - walletExternal description: Type discriminator. category: type: string enum: - crypto description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/WalletExternalDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: Externally-custodied crypto wallet instrument. title: External wallet WalletFiatInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - walletFiat description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/WalletFiatInstrumentDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: |- Fiat balance wallet instrument — a USD balance held at a partner bank (Erebor Bank, N.A.). No network or on-chain address; an internal ledger. title: Fiat wallet BankUsInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - bankUs description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/BankUsDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: US bank account instrument. title: US bank account BankIbanInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - bankIban description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/BankIbanDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: IBAN bank account instrument. title: IBAN bank account BankCanadaInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - bankCanada description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/BankCanadaDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: Canadian bank account instrument. title: Canadian bank account CardInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - card description: Type discriminator. category: type: string enum: - fiatAccount description: >- High-level grouping: `fiatAccount` for bank or card accounts, `crypto` for wallets. details: $ref: '#/components/schemas/CardDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: Card instrument. title: Card CashInstrument: type: object required: - type - category - details - displayName properties: party: $ref: '#/components/schemas/Party' type: type: string enum: - cash description: Type discriminator. category: type: string enum: - cash description: 'High-level grouping: always `cash` for cash pickups and drops.' details: $ref: '#/components/schemas/CashDetails' displayName: type: string description: >- Opaque, render-only summary of this instrument for list/detail display (v0.12, #2665) — format is not contractual and may change without a version bump. Never a full account number/IBAN/PAN. description: Cash instrument. title: Cash int64String: type: string description: Wire-safe integer string for fiat amounts within int64 range. x-go-type-import: path: github.com/0xPolygon/bpn-lib/numeric x-go-type: numeric.Int64String BankUsSideDetails: type: object required: - id - asset - network - accountHolder properties: id: type: string description: US bank ExternalAccount ID (ext_bankUs_ prefix). asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - ach - achSameDay - wire description: Network identifier. accountHolder: $ref: '#/components/schemas/AccountHolder' memo: type: string allOf: - $ref: '#/components/schemas/paymentMemo' nullable: true description: >- Optional customer-supplied payment memo delivered to the beneficiary's bank. HONORED TODAY ON: a Deposit Address `bankUs` destination with `network: "wire"` (create and update). The stored value replaces — it does not append to — the memo OMS would otherwise generate for every outbound Fedwire payout from that deposit address. Send `null` (or omit it on an update that replaces `destination`) to restore the generated memo. Because the memo is read when each payout wire is built, an edit affects only future payouts, never one already in flight. REJECTED EVERYWHERE ELSE, with `422 memoNotSupported`: this model is shared by the Quote and Virtual Account request surfaces (create and update), and by a deposit-address `bankUs` destination on the `ach` / `achSameDay` rails. A non-empty memo on any of those is refused rather than accepted and dropped — a silently ignored field on a money path gives the caller a success response while the payout carries the generated memo. Sending `null`, omitting the field, or sending only whitespace is always accepted (it means "no override"). Each rejected surface becomes accepting as its slice ships (omsx#2254); relaxing a 422 into an accepted value never breaks a caller, so no client needs to change when that happens. The error body's `details.reason` tells apart a temporary gap from a permanent one: `"notImplemented"` means this surface/rail will accept the field once its omsx#2254 slice ships (every current rejection above is this case); `"unsupportedRail"` would mean the field is not a concept on this rail and never will be (e.g. the shared model also carries fields that are rail-specific by design, like ACH's `companyDiscretionaryData` on a wire destination) — retry the first after a release, never the second. companyDiscretionaryData: type: string allOf: - $ref: '#/components/schemas/companyDiscretionaryData' nullable: true description: >- Optional ACH-only field for the originator's internal use (NACHA batch header). See the companyDiscretionaryData scalar doc. Honored only when network is "ach" or "achSameDay"; 422 memoNotSupported on "wire". decimalString: type: string description: >- Wire-safe decimal string for financial float values (USD amounts, percentages). x-go-type-import: path: github.com/shopspring/decimal x-go-type: decimal.Decimal BankIbanSideDetails: type: object required: - id - asset - accountHolder properties: id: type: string description: IBAN ExternalAccount ID (ext_bankIban_ prefix). asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - swift description: Network identifier. default: swift accountHolder: $ref: '#/components/schemas/AccountHolder' memo: type: string allOf: - $ref: '#/components/schemas/paymentMemo' nullable: true description: >- Optional customer-supplied payment memo delivered via SWIFT remittance information. See BankUsSideDetails.memo's doc for the full contract — this is the same field, same charset/length bound, same honored-surface table, applied to the SWIFT rail instead of Fedwire. BankCanadaSideDetails: type: object required: - id - asset - network - accountHolder properties: id: type: string description: Canadian bank ExternalAccount ID (ext_bankCa_ prefix). asset: type: string enum: - usd - cad description: Canonical asset identifier. network: type: string enum: - swift - local description: USD uses `swift`; CAD uses `local`. Always explicit. accountHolder: $ref: '#/components/schemas/AccountHolder' memo: type: string allOf: - $ref: '#/components/schemas/paymentMemo' nullable: true description: >- Optional customer-supplied payment memo, honored only on the USD/swift leg (this model's `local`/CAD leg has no memo concept — Erebor's local Canadian rail carries no remittance-information field). See BankUsSideDetails.memo's doc for the full contract. WalletCryptoSideDetails: type: object required: - id - asset - network properties: id: type: string description: OMS wallet ID (wlt_ prefix). asset: type: string description: 'Crypto asset. One of: usdc, usdt.' network: allOf: - $ref: '#/components/schemas/CryptoNetwork' description: Network identifier. WalletExternalRegisteredSideDetails: type: object required: - id - asset - network properties: id: type: string description: Registered ExternalAccount ID (ext_wlt_ prefix). Required. asset: type: string description: 'Crypto asset. One of: usdc, usdt.' network: allOf: - $ref: '#/components/schemas/CryptoNetwork' description: Network identifier. WalletFiatSideDetails: type: object required: - id - asset properties: id: type: string description: OMS fiat wallet ID (wlt_fiat_ prefix). asset: type: string enum: - usd description: Fiat currency. Only `usd` today. AssetNetworkPair: type: object required: - asset - network properties: asset: type: string network: type: string description: 'One (asset, network) tuple — e.g. `{ asset: "usd", network: "ach" }`.' BankRoutingBlockBeneficiary: type: object required: - name - address properties: name: type: string address: type: string description: |- Beneficiary on a bank routing block - the entity to which the funds are ultimately credited. For SWIFT this is Erebor (the bank); for domestic rails this is the customer. Response-only, system-synthesised (Erebor entity or customer counterparty). The address is a single formatted display line (spec §BankRoutingBlock), e.g. "6 Acme Way, Bentonville, AR 72712 US". Party: type: object oneOf: - $ref: '#/components/schemas/PartyCustomer' - $ref: '#/components/schemas/PartyOtherCustomer' - $ref: '#/components/schemas/PartyExternalRegistered' - $ref: '#/components/schemas/PartyExternalUnregistered' discriminator: propertyName: relationship mapping: customer: $ref: '#/components/schemas/PartyCustomer' otherCustomer: $ref: '#/components/schemas/PartyOtherCustomer' externalRegistered: $ref: '#/components/schemas/PartyExternalRegistered' externalUnregistered: $ref: '#/components/schemas/PartyExternalUnregistered' WalletCryptoDetails: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: >- Internal OMS wallet (`wlt_` prefix; legacy `acc_` also accepted on input). asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. blockchainAddress: type: string description: On-chain address. custodyType: type: string enum: - custodial - embedded description: 'How the wallet is held: `custodial` or `embedded`.' txHash: type: string description: On-chain transaction hash. blockchainAsset: allOf: - $ref: '#/components/schemas/BlockchainAsset' description: >- BPN extension: resolved on-chain asset identity (protocol/chainId/tokenId). description: 'WalletCrypto instrument details: an OMS-custodied crypto wallet.' WalletExternalDetails: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Unique identifier. asset: type: string description: Canonical asset identifier. network: type: string description: Network identifier. blockchainAddress: type: string description: On-chain address. custodian: type: string description: Custodian holding the funds. otherCustodian: type: string description: Free-text custodian name when `custodian` is `other`. txHash: type: string description: On-chain transaction hash. blockchainAsset: allOf: - $ref: '#/components/schemas/BlockchainAsset' description: >- BPN extension: resolved on-chain asset identity (protocol/chainId/tokenId). description: >- WalletExternal instrument details: a crypto wallet held in external custody. WalletFiatInstrumentDetails: type: object properties: id: type: string description: >- OMS fiat wallet ID (`wlt_fiat_` prefix). Look up via `GET /wallets`. Plain string, not the `typeId` scalar: `wlt_fiat_` is a two-token prefix, which the single-underscore `typeId` pattern cannot validate. Matches the sibling `WalletFiatSideDetails.id` in quote.tsp. asset: type: string enum: - usd description: Fiat currency of the balance. Only `usd` today. network: type: string enum: - bookTransfer description: >- Read-only settlement rail marker (ratified v0.12): `bookTransfer` when this walletFiat is the destination of a Virtual Account / Deposit Address book-transfer credit — an internal ledger movement at the partner bank, no external rail. Absent when the walletFiat is a funding source. provider: type: string description: >- Legal entity holding the balance (e.g. "Erebor Bank, N.A."). Read-only. description: >- WalletFiat instrument details: a fiat balance wallet held at a partner bank (e.g. USD at Erebor Bank, N.A.). No on-chain address — an internal ledger balance. `network` is `bookTransfer` only when the wallet is a VA/DA destination credited by internal book transfer (v0.12, #2504). BankUsDetails: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Unique identifier. asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - ach - achSameDay - wire description: Network identifier. secCode: allOf: - $ref: '#/components/schemas/SecCode' description: ACH SEC code (populated only on ach/achSameDay). accountNumberLast4: type: string description: Last four digits of the account number. routingNumber: type: string description: US ABA routing number. bankName: type: string description: Bank display name. accountType: type: string enum: - checking - savings description: checking or savings. memo: type: string description: Payment memo. companyDiscretionaryData: type: string description: >- Optional ACH-only field for the originator's internal use (NACHA batch header). See the companyDiscretionaryData scalar doc (quote.tsp). Echoed back only when the stored deposit-address destination carries one (ach/ achSameDay only — never on wire). description: US bank account instrument details. BankIbanDetails: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Unique identifier. asset: type: string description: Canonical asset identifier. network: type: string enum: - swift description: Network identifier. ibanLast4: type: string description: Last four characters of the IBAN. BIC: type: string description: SWIFT BIC. bankAddress: $ref: '#/components/schemas/Address' countryCode: type: string description: ISO 3166-1 alpha-2 country code. memo: type: string description: Payment memo. description: IBAN bank account instrument details. BankCanadaDetails: type: object properties: id: allOf: - $ref: '#/components/schemas/typeId' description: Unique identifier. asset: type: string enum: - usd - cad description: Canonical asset identifier. network: type: string enum: - swift - local description: Network identifier. institutionNumber: type: string description: Canadian 3-digit institution number. transitNumber: type: string description: Canadian 5-digit transit number. accountNumberLast4: type: string description: Last four digits of the account number. bankName: type: string description: Bank display name. memo: type: string description: Payment memo. description: Canadian bank account instrument details. CardDetails: type: object properties: id: type: string description: Unique identifier. asset: type: string enum: - usd description: Canonical asset identifier. network: type: string enum: - card description: Network identifier. cardNumberLast4: type: string description: Last four digits of the card number. cardProvider: type: string description: Card network/provider. memo: type: string description: Payment memo. description: Card instrument details. CashDetails: type: object properties: asset: type: string description: Canonical asset identifier. cashLocationId: type: string description: Cash location ID from `GET /cash-locations`. cashLocationReference: type: string description: Provider reference for the location, from `GET /cash-locations`. pickupCode: type: string description: >- Retail pickup code for a cash payout. Populated only on the cash-out (pickup) side. expiresAt: type: string format: date-time description: Pickup-code expiry. Populated only on the cash-out (pickup) side. locationName: type: string description: >- Display name of the retail pickup location. Populated only on the cash-out (pickup) side. locationAddress: type: string description: >- Street address of the retail pickup location. Populated only on the cash-out (pickup) side. description: Cash pickup/drop instrument details. AccountHolder: type: string enum: - customer description: >- Who holds the payout bank account (OMS closed enum). `customer` is the only valid value. paymentMemo: type: string maxLength: 140 pattern: ^[A-Za-z0-9 /?:().,'+\-]*$ description: >- Customer-supplied payment memo carried to the beneficiary's bank in the ISO 20022 unstructured remittance-information field. Allowed characters are the ISO 20022 set only: letters, digits, space and `/?:().,'+-`. `maxLength` is the ISO 20022 OUTER bound (140), which is what Fedwire and SWIFT accept. Per-rail rules are enforced server-side rather than in the schema. Note that ACH is not simply shorter: the NACHA addenda record is a different character set (uppercase only, no `/`, but `&=@_#%` allowed) capped at 80, so the two sets overlap without either containing the other. The pattern below MUST stay byte-identical to `iso20022.CharsetPattern` (`lib/iso20022/charset.go`), the Go-side authority the request validators and the outbound memo builders share. `TestCharsetPatternMatchesTypeSpec` reads this file and fails if the two drift. x-go-type: string companyDiscretionaryData: type: string maxLength: 20 pattern: ^[A-Z0-9 &\-\.\$*\/#@%]*$ description: |- Optional ACH-only field for the originator's internal use, carried verbatim in the NACHA batch header (companyDiscretionaryData). Distinct from `memo`: this never reaches the beneficiary, it is BPN's own origination metadata. Uppercase NACHA character set, max 20 characters. Rejected with 422 memoNotSupported on any destination that is not an ACH bankUs destination. CryptoNetwork: type: string enum: - ethereum - polygon - base - solana description: >- Wire vocabulary for a crypto `network` request field: ethereum, polygon, base, solana. This is vocabulary, not availability — which of these a given destination type actually accepts is enforced at runtime per destination type against the narrower Erebor-served set, so `polygon` is legal on the wire but currently rejected wherever Erebor does not serve it. Numeric EVM chain ids (e.g. "1", "137", "8453") were never accepted by BPN — no chain-id-to-name coercion exists, so nothing here deprecates prior behavior. Values are lowercase on the wire; the server additionally normalizes case and surrounding whitespace on input, so this schema is stricter than the server in that one dimension — send lowercase, untrimmed-safe values to stay strictly schema-valid. A `network` field may be typed `CryptoNetwork` regardless of whether it appears on a response, as long as its sole writer is gated by `eanetworks.AllServedNetworks()` — a runtime-enforced subset of this enum, with the containment itself enforced by `TestCryptoNetwork_SupersetOfServedNetworks` (services/externalaccount/networks/networks_test.go). That guarantee is what makes the enum safe there: the value can never leave the enum's vocabulary no matter which code path renders it. A `network` field whose writer is NOT so gated stays `string` pending #2666's outbound enum guard — for such a field, a stored value outside the enum would break a strict partner client validator (this happened in production: #2528). `chain` fields are deliberately excluded too: their vocabulary is wider and includes `bitcoin`, which this enum does not carry. PartyCustomer: type: object required: - relationship - customerId properties: relationship: type: string enum: - customer description: Relationship discriminator. entityType: $ref: '#/components/schemas/OwnerType' customerId: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer that owns this record (`cst_` prefix). description: The owning OMS customer is on this side. title: Customer PartyOtherCustomer: type: object required: - relationship - customerId properties: relationship: type: string enum: - otherCustomer description: Relationship discriminator. entityType: $ref: '#/components/schemas/OwnerType' customerId: allOf: - $ref: '#/components/schemas/typeId' description: The OMS customer that owns this record (`cst_` prefix). name: type: string nullable: true description: Display name. description: A different OMS customer is on this side. title: Another customer PartyExternalRegistered: type: object required: - relationship - counterpartyId properties: relationship: type: string enum: - externalRegistered description: Relationship discriminator. entityType: $ref: '#/components/schemas/OwnerType' counterpartyId: allOf: - $ref: '#/components/schemas/typeId' description: Counterparty ID (`ctp_` prefix). name: type: string nullable: true description: Display name. address: type: object allOf: - $ref: '#/components/schemas/Address' nullable: true description: Postal address. description: A registered counterparty (saved third party) is on this side. title: Registered external account PartyExternalUnregistered: type: object required: - relationship properties: relationship: type: string enum: - externalUnregistered description: Relationship discriminator. name: type: string nullable: true description: Display name. address: type: object allOf: - $ref: '#/components/schemas/Address' nullable: true description: Postal address. description: >- An unrecognized external party (no saved record) is on this side. There is no OMS record behind it, so it carries no entityType. title: Unregistered external account BlockchainAsset: type: object required: - protocol - chainId - tokenId properties: protocol: $ref: '#/components/schemas/BlockchainProtocol' chainId: type: string tokenId: type: string SecCode: type: string enum: - ccd - ppd - web description: >- ACH SEC code. Populated only when the destination bank network is `ach`/`achSameDay`; null otherwise. Server-derived from the destination owner's and the source customer's `entityType`. Address: type: object properties: line1: type: string description: Street address, line 1. line2: type: string description: Street address, line 2. city: type: string description: City. state: type: string description: State / province / region. country: type: string description: ISO 3166-1 alpha-2 zipCode: type: string description: ZIP / postal code. description: A postal address. country is an ISO 3166-1 alpha-2 country code. OwnerType: type: string enum: - individual - business BlockchainProtocol: type: string enum: - evm - svm - sui securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token from POST /auth/token ````