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.

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
string

Set when status = invalid (derived from payout returns). Free-text for now; a closed enum lands with the invalidation transition logic.

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.