ALalfredpay
Linked Accounts

Register a payout destination

Changed on

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.

Wait on linked_account.updated reaching VERIFIED. See Webhooks and events.

post/v1/customers/{customerId}/linked_accounts

Request

  • Base URL
    https://api.sandbox.alfredpay.io
  • URL
    https://api.sandbox.alfredpay.io/v1/customers/{customerId}/linked_accounts
  • Auth
    • HTTP bearer
    • or API key in header api-key and API key in header api-secret

Headers

Idempotency-Keystring 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.

Request body

destinationType'BANK_ACCOUNT' | 'WALLET' 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).

country'MEX' | 'ARG' | 'BRA' | 'COL' | 'CHL' | 'PER' | 'DOM' | 'USA' | 'CHN' | 'HKG' | 'BOL' | 'PRY'

ISO 3166-1 alpha-3, the only form Alfred stores, filters on, reports or emits. Compatibility rule for integrations that can only send alpha-2: any inbound country value in alpha-2 (path, query or body) is normalized to alpha-3 at the boundary before validation, storage or routing. Unrecognized in either form → 422 validation_error.

currency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT'

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

holderNamestring

The registered holder. Alfred derives relationship_type from it.

holderTaxIdstring
chain'SOL' | 'ETH' | 'MATIC' | 'BASE' | 'ARB' | 'OP' | 'AVAX' | 'BNB' | 'TRX' | 'XLM' | 'CELO'
addressstring

Required for WALLET.

metadataMetadata

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

Response

Created

idstring
customerIdstring
destinationType'BANK_ACCOUNT' | 'WALLET'

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

country'MEX' | 'ARG' | 'BRA' | 'COL' | 'CHL' | 'PER' | 'DOM' | 'USA' | 'CHN' | 'HKG' | 'BOL' | 'PRY'

ISO 3166-1 alpha-3, the only form Alfred stores, filters on, reports or emits. Compatibility rule for integrations that can only send alpha-2: any inbound country value in alpha-2 (path, query or body) is normalized to alpha-3 at the boundary before validation, storage or routing. Unrecognized in either form → 422 validation_error.

currency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT'

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

supportedRailsRail[]

Derived by Alfred at registration from country and identifier type. A payout or quote must use one of these.

identifierTypestring nullable
identifierMaskedstring nullable

Last four characters only.

holderNamestring
createdAtstring date-time

Changes