Register a payout destination

post

https://api.sandbox.alfredpay.io/v1/customers/{customerId}/linked_accounts

One object covers bank accounts and wallets. destinationType says which.

You register what the money lands in, meaning country, currency and identifiers. You never register a rail. Alfred derives supportedRails[] from the country and the identifier type:

a CLABE becomes [SPEI]
a US routing and account number becomes [ACH, WIRE]
a Hong Kong account becomes [FPS, CHATS]

Whether the destination belongs to the customer or a third party is derived from the registered holder and returned as relationship.relationship_type. It's never something you declare.

Wallets need only chain and address. TRM screens every wallet, and that screening is the whole control: there's no challenge to sign and no attestation to supply.

A destination whose route isn't LIVE is refused with route_unsupported at registration. Wait for relationship_status: VERIFIED before you pay out to it.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

customerId

string

required

Body Params

destinationType

string

enum

required

What kind of thing the money lands in. Kept separate from the rail (how it gets there) and from the provider (who carries it).

Allowed:

country

string

enum

Required for BANK_ACCOUNT; omitted for WALLET.

currency

string

enum

Required for BANK_ACCOUNT. Must be a currency the route supports in this country.

holderName

string

The registered holder. Alfred derives relationship_type from it.

holderTaxId

string

bankAccount

object

BANK_ACCOUNT only. Which fields are required is the route's fields[] on GET /v1/countries/{country}. Identifiers, not rails.

chain

string

enum

Required for WALLET.

address

string

Required for WALLET.

metadata

object

Client-supplied key–value pairs, echoed on the object and every event about it.

Headers

Idempotency-Key

uuid

required

Required on every state-changing POST, simulators included; the only exempt POST is …/verifications/preflight.
Replay (same key, same body) returns the original response with Idempotent-Replayed: true; same key with a
different body → 409 idempotency_conflict. Keys are UUIDs, scoped to the API key, retained for 24 hours.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Created

400Malformed request, so a missing required field, a wrong type or a bad enum.

422Semantically invalid. The request is well-formed but violates a business rule. param names the field.