Skip to main content
PATCH
Update an External Account

Authorizations

Authorization
string
header
required

Token from POST /auth/token

Path Parameters

externalAccountId
string
required

External Account ID (ext_ prefix).

Body

application/json

Partial update - only label and metadata are mutable. Financial / identity fields are immutable (re-pointing a destination is create-new + re-point). Any other JSON key in the body is rejected with 400.

label
string

Optional display label.

metadata
object

Free-form key-value pairs stored on the resource and echoed back on reads.

Response

200 - application/json

The request has succeeded.

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.

id
string

External Account ID (ext_ prefix).

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})$
object
enum<string>

Resource type discriminator. Always "externalAccount".

Available options:
externalAccount
owner
Customer-owned · object

Who owns this account: the customer or one of their counterparties.

ownerDisplayName
string

Resolved display name of the customer owner, for list/detail rendering without a follow-up fetch (v0.12 list enrichment, #2520/#2665). Present only when owner.kind = customer; absent for counterparty-owned accounts — no counterparty-name resolver is wired for this resource.

customer
object

Resolved id + display name of the owning customer. Present only when owner.kind = customer; absent for counterparty-owned accounts.

type
enum<string>

The instrument type; determines which detail object is populated.

Available options:
bankUs,
bankIban,
bankCanada,
card,
walletExternal
category
enum<string>

High-level grouping: fiatAccount for bank or card accounts, crypto for wallets. The same value as the instrument category when this account is referenced in a transaction.

Available options:
fiatAccount,
crypto
status
enum<string>

Current lifecycle status. A transition to invalid always fires the externalAccount.statusChanged webhook.

Available options:
active,
pending,
rejected,
invalid,
deleted,
failed
failureReason
enum<string>

Set when status = failed.

Available options:
ereborRejected,
cardProviderRejected,
providerAccountMissing,
cardLimitReached,
cardInUse,
provisioningTimeout,
systemError
failureDetail
object

Structured provider rejection detail. Set when status = failed and the failure was a provider terminal rejection; absent for provisioning timeouts and internal failures.

rejectionReason
string

Set when status = rejected (compliance screening).

invalidReason
enum<string>

Set when status = invalid (derived from payout returns).

Available options:
accountClosed,
accountFrozenByBank,
routingOrAccountNumberInvalid,
accountHolderDeceased,
accountDoesNotSupportTransfers,
payeeNameMismatch,
walletUnreachableOnNetwork,
billingAddressMismatch,
cardExpired,
cardClosedOrLostStolen,
pushToCardUnsupported,
cardDeclinedByIssuer
invalidReasonCode
string

The provider's own code for the failure behind invalidReason, verbatim. For US bank accounts, this is the NACHA return code from the failed payout (for example, R15). Absent when the provider gave no code or when the account was invalidated by something other than a returned payment. Read invalidReason to decide what to do; read this field only for support or reconciliation.

label
string

Optional display label.

metadata
object

Free-form key-value pairs supplied at creation or update.

bankUs
object

Populated when type = bankUs.

bankIban
object

Populated when type = bankIban.

bankCanada
object

Populated when type = bankCanada.

walletExternal
object

Populated when type = walletExternal.

card
object

Populated when type = card.

resolvedTransactions
string[]

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

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

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})$
createdAt
string<date-time>

When the external account was registered.

updatedAt
string<date-time>

When the external account was last updated.