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.
Authorizations
Token from POST /auth/token
Headers
Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.
Body
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.
Customer-owned External Account.
- Option 1
- Option 2
External Account type. Selects which per-type detail object the request must carry.
bankUs, bankIban, bankCanada, card, walletExternal Required when type = bankCanada.
Required when type = bankIban.
Required when type = bankUs.
Required when type = card.
Required when type = walletExternal.
Response
The request has succeeded and a new resource has been created as a result.
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.
Populated when type = bankCanada.
Populated when type = bankIban.
Populated when type = bankUs.
Populated when type = card.
Coarse classification derived from type, stored for query convenience.
fiatAccount, crypto Set when status = failed.
ereborRejected, cardProviderRejected, providerAccountMissing, cardLimitReached, cardInUse, provisioningTimeout, systemError externalAccount Customer-owned External Account.
- Option 1
- Option 2
Set when status = rejected (compliance screening).
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).
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.
active, pending, rejected, invalid, deleted, failed External Account type. Selects which per-type detail object the request must carry.
bankUs, bankIban, bankCanada, card, walletExternal Populated when type = walletExternal.