---
title: "Register a payout destination"
method: POST
path: "/v1/customers/{customerId}/linked_accounts"
tags: ["Linked Accounts"]
---

# Register a payout destination

`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: one of:
  - HTTP bearer
  - API key in header `api-key` and API key in header `api-secret`

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](/docs/webhooks-and-events).

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- LinkedAccountCreate
  - `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`.
  - `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.
    - `identifierType` 'CLABE' | 'CBU' | 'CVU' | 'ALIAS' | 'PIX_KEY' | 'ACCOUNT_NUMBER' | 'ROUTING_AND_ACCOUNT' | 'IBAN' | 'PHONE': The kind of account identifier the partner registers. Never a rail. A CLABE is reachable over SPEI, a US routing and account number over ACH and WIRE.
    - `identifier` string: The CLABE, CBU/CVU, alias, PIX key, IBAN or account number.
    - `routingNumber` string: USA only, with ROUTING_AND_ACCOUNT.
    - `bankCode` string
    - `bankName` string
    - `accountClass` 'CHECKING' | 'SAVINGS'
    - `pixKeyType` 'CPF' | 'CNPJ' | 'PHONE' | 'EMAIL' | 'EVP': BRA only, with PIX_KEY.
  - `chain` 'SOL' | 'ETH' | 'MATIC' | 'BASE' | 'ARB' | 'OP' | 'AVAX' | 'BNB' | 'TRX' | 'XLM' | 'CELO'
  - `address` string: Required for WALLET.
  - `metadata` Metadata: Client-supplied key–value pairs, echoed on the object and every event about it.

## Response `201`

Created

- LinkedAccount
  - `id` string
  - `customerId` string
  - `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`.
  - `supportedRails` Rail[]: Derived by Alfred at registration from country and identifier type. A payout or quote must use one of these.
  - `identifierType` string, nullable
  - `identifierMasked` string, nullable: Last four characters only.
  - `holderName` string
  - `relationship` Relationship
    - `relationship_type` 'BANK_ACCOUNT_OWNERSHIP' | 'WALLET_OWNERSHIP' | 'THIRD_PARTY_BENEFICIARY': Derived by Alfred from the registered holder, never declared.
    - `relationship_status` 'PENDING' | 'VERIFIED' | 'REJECTED' | 'EXPIRED' | 'REVOKED'
    - `allowed_use_cases` string[]
    - `restrictions` string[]
    - `evidence_reference` string[]
    - `start_date` string, date-time
    - `end_date` string, date-time, nullable
  - `createdAt` string, date-time

## Other responses

- `400`: Malformed request, so a missing required field, a wrong type or a bad enum.
- `422`: Semantically invalid. The request is well-formed but violates a business rule. `param` names the field.

## Changes

- **2026-11-03** `20fef4fd2ab3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/changes/v1/customers/:customerId/linked_accounts/post.md)

---

[API](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation.md) - [All operations](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/revisions/20fef4fd2ab3?raw)