Sign in

v1

latestOpenAPI 3.0.32026-07-2650226215.9 KB
ExternalAccount

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.

post/external-accounts

Headers

Idempotency-Keystring required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Request body

type'bankUs' | 'bankIban' | 'bankCanada' | 'card' | 'walletExternal' required

External Account type. card is created only via the dedicated POST /external-accounts/cards endpoint; supplying type = card to the generic create is rejected with 422 cardMustUseCardEndpoint. card and walletExternal remain valid for reads, lists, get and delete.

labelstring

Optional display label.

metadataobject

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

Response

The request has succeeded and a new resource has been created as a result.

idstring

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

object'externalAccount'

Resource type discriminator. Always "externalAccount".

type'bankUs' | 'bankIban' | 'bankCanada' | 'card' | 'walletExternal'

External Account type. card is created only via the dedicated POST /external-accounts/cards endpoint; supplying type = card to the generic create is rejected with 422 cardMustUseCardEndpoint. card and walletExternal remain valid for reads, lists, get and delete.

category'fiatAccount' | 'crypto'

Coarse classification derived from type, stored for query convenience.

status'active' | 'pending' | 'rejected' | 'invalid' | 'deleted' | 'failed'

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.

failureReason'ereborRejected' | 'cardProviderRejected' | 'providerAccountMissing' | 'cardLimitReached' | 'cardInUse' | 'provisioningTimeout' | 'systemError'

Closed enum stamped on an External Account when status = failed.

rejectionReasonstring

Set when status = rejected (compliance screening).

invalidReasonstring

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

labelstring

Optional display label.

metadataobject

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

resolvedTransactionsTypeId[]

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

createdAtstring date-time

When the external account was registered.

updatedAtstring date-time

When the external account was last updated.