Payout Destinations

How to register where money goes.

A destination, or recipient, is a bank account or wallet you pay out to. You can register one in two places.

Registered onCallPaid from
Your own accountPOST /v1/linked_accountsYour own balance
A customerPOST /v1/customers/{customerId}/linked_accountsThat customer's balance

The same object covers both kinds of destination. destinationType says which one you mean, either BANK_ACCOUNT or WALLET.

Recipients on your own account

POST /v1/linked_accounts

A recipient registered here belongs to your own account rather than to a customer, and it is paid from your own balance. Use it for payouts you make on behalf of your own users, where the recipient is identified and screened but not onboarded. The response carries your own account as customerId.

Declare the relationship. relationshipType is required on every recipient you register here.

relationshipTypeMeans
FIRST_PARTYAn account or wallet you hold yourself
THIRD_PARTYA beneficiary you pay, such as a supplier, a contractor or a payee

Say who the holder is. holderType is INDIVIDUAL for a person or BUSINESS for a company, in uppercase. It's required on a THIRD_PARTY recipient and optional on FIRST_PARTY. A third-party recipient without it is refused with 400 validation_error, and details.issues[].path names holderType.

A bank account

{
  "destinationType": "BANK_ACCOUNT",
  "relationshipType": "THIRD_PARTY",
  "holderType": "BUSINESS",
  "country": "ARG",
  "currency": "ARS",
  "holderName": "Proveedora Norte S.A.",
  "holderTaxId": "30711610126",
  "bankAccount": {
    "identifierType": "CBU",
    "identifier": "2850590940090418135201"
  }
}
FieldRequiredNotes
destinationTypeYesBANK_ACCOUNT
relationshipTypeYesFIRST_PARTY or THIRD_PARTY
holderTypeTHIRD_PARTYINDIVIDUAL or BUSINESS. Optional on FIRST_PARTY
countryYesISO alpha-3
currencyYesISO 4217
holderNameYesThe account holder's legal name
holderTaxIdNoThe holder's tax ID, such as a CUIT in Argentina. Send it whenever you have it
bankAccount.identifierTypeYesSee the table below
bankAccount.identifierYesThe CLABE, CBU, CVU, account number or PIX key
bankAccount.bankCodeColombiaThe beneficiary's bank, as the code from GET /v1/countries/COL/banks. See Bank codes
bankAccount.routingNumberUnited StatesWith ROUTING_AND_ACCOUNT
bankAccount.pixKeyTypeBrazilCPF, CNPJ, PHONE, EMAIL or EVP

You never name a rail. Alfred derives it from the country and the identifier type.

CountryidentifierTypesupportedRails[]
MexicoCLABE[SPEI]
ArgentinaCBU or CVU, 22 digits[COELSA]
BrazilPIX_KEY, with pixKeyType[PIX]
United StatesROUTING_AND_ACCOUNT or ACCOUNT_NUMBER[ACH]
ColombiaACCOUNT_NUMBER, with bankCode[ACH]

A combination with no rail is refused with 422 route_unsupported.

A wallet

{
  "destinationType": "WALLET",
  "relationshipType": "THIRD_PARTY",
  "holderType": "INDIVIDUAL",
  "chain": "BASE",
  "address": "0xb7e4d2f8a1c3964205e8f7d6b0a1c2e3f4950617"
}

A wallet needs chain and address, plus holderType when it's third party, and no holder name. It registers for USDC and is valued in USD. chain is one of SOL, ETH, BASE, MATIC, ARB, OP, AVAX, BNB, CELO, XLM or TRX. A chain that can't be screened is refused with route_unsupported.

When it can be paid

TypeOn creationCan be paid
Bank accountrelationship_status: VERIFIEDStraight away
Walletrelationship_status: PENDINGOnce on-chain screening clears and it reaches VERIFIED, normally within moments

Read a wallet back with GET /v1/linked_accounts/{linkedAccountId} to see it reach VERIFIED. A payout to a recipient in any other state is refused with recipient_not_linked.

What comes back

{
  "id": "link_67b2ffa9a92147419ff969f3248419ad",
  "customerId": "acct_...",
  "destinationType": "BANK_ACCOUNT",
  "country": "ARG",
  "currency": "ARS",
  "supportedRails": ["COELSA"],
  "identifierMasked": "5201",
  "holderName": "Proveedora Norte S.A.",
  "relationship": {
    "relationship_type": "THIRD_PARTY",
    "relationship_status": "VERIFIED",
    "allowed_use_cases": []
  },
  "createdAt": "2026-10-26T12:26:03.906Z"
}
FieldWhat it is
idThe recipient's ID, link_.... Every payout to it uses this
customerIdYour own account
countryISO alpha-3 for a bank account, null for a wallet
supportedRailsThe rails it can be reached on
identifierMaskedThe last four characters of the identifier
holderNameThe holder's name, and an empty string for a wallet
relationshiprelationship_type, relationship_status and allowed_use_cases

Bank codes

A Colombian bank account needs bankAccount.bankCode, whether you register it on your own account or on a customer. Read the codes from the bank list:

GET /v1/countries/COL/banks
{
  "data": [
    { "id": "31", "name": "BANCOLOMBIA", "code": "001007" }
  ]
}
FieldWhat it is
nameThe bank's name, to show in your bank picker
codeWhat you send as bankAccount.bankCode
idAlfred's own reference for the bank. You don't send it anywhere

Send code exactly as returned, leading zeros included. The list can grow as banks are added, so read it when you build or refresh your form rather than hard-coding codes.

{
  "destinationType": "BANK_ACCOUNT",
  "relationshipType": "THIRD_PARTY",
  "holderType": "BUSINESS",
  "country": "COL",
  "currency": "COP",
  "holderName": "Distribuidora Andina S.A.S.",
  "holderTaxId": "9001234567",
  "bankAccount": {
    "identifierType": "ACCOUNT_NUMBER",
    "identifier": "12345678901",
    "bankCode": "001007"
  }
}

On a customer, drop relationshipType and holderType and send the same body to POST /v1/customers/{customerId}/linked_accounts.

Recipients on a customer

The rest of this page covers destinations registered on a customer with POST /v1/customers/{customerId}/linked_accounts, which are paid from that customer's balance.

What you register

Send the country, the currency and the identifiers. You do not send a rail.

Alfred derives supportedRails[] from what you sent:

You registerYou get back
A CLABE in Mexico[SPEI]
A US routing and account number[ACH, WIRE]
A Hong Kong account[FPS, CHATS]

The fields a given route needs are listed in the route registry, on GET /v1/countries/{country}. Build your form from the registry, because that is what stays current.

{
  "destinationType": "BANK_ACCOUNT",
  "country": "MEX",
  "currency": "MXN",
  "holderName": "Proveedora del Norte S.A. de C.V.",
  "bankAccount": {
    "identifierType": "CLABE",
    "identifier": "012180015555555555"
  }
}

A destination whose route isn't LIVE is refused at registration with route_unsupported. You find out at registration time instead of when you try to pay out.

Alfred verifies who owns the account

You don't declare whether a destination belongs to the customer or to a third party. Alfred decides it during verification, from the provider's account validation and a name match against the customer's verified identity, not from the holder name you send. The result is returned as relationship.relationship_type:

  • BANK_ACCOUNT_OWNERSHIP or WALLET_OWNERSHIP for the customer's own
  • THIRD_PARTY_BENEFICIARY for anyone else

This matters because the third-party endorsement check keys off that value. You can't override it by asserting something different in your request.

Wallets

{
  "destinationType": "WALLET",
  "chain": "SOL",
  "address": "..."
}

A wallet destination needs only the chain and the address.

TRM screens every wallet, and that screening is the whole control. You don't sign a challenge, supply an attestation or complete a proof-of-control step on your side. The TRM result is what moves the relationship to VERIFIED, and it is also what refuses an address.

Wait for VERIFIED

Wait on linked_account.updated reaching relationship_status: VERIFIED.

A payout to a destination in any other state is refused with recipient_not_linked before anything is locked.

StatusCan receive a payout
PENDINGNo, screening is still in progress.
VERIFIEDYes.
REJECTEDNo.
EXPIREDNo.
REVOKEDNo.

EXPIRED matters as much as REJECTED. A relationship has a validity window, so a destination that worked last quarter can stop working without anyone touching it. Integrations that only handle the move from PENDING to VERIFIED tend to miss this case.

The allowed_use_cases field is worth reading too. A destination approved for PAYOUT but not for COLLECTION will refuse a collection, and this field tells you before you try.

Reading and removing

GET    /v1/customers/{customerId}/linked_accounts
GET    /v1/linked_accounts/{linkedAccountId}
DELETE /v1/linked_accounts/{linkedAccountId}

The single read returns the derived supportedRails[], the relationship, the use cases it's approved for and its validity window.

Deleting revokes the relationship. Payouts already in flight still complete, and new ones are refused.

GET /v1/linked_accounts/{linkedAccountId} and DELETE /v1/linked_accounts/{linkedAccountId} work the same way for recipients on your own account.

The same counterparty can be linked more than once. That is normal when someone has accounts on different rails or in different currencies.

In sandbox

POST /v1/test/linked_accounts/{linkedAccountId}/simulate_activation

This moves a relationship straight to VERIFIED without the review queue. The review queue is the one step of a payout whose timing you otherwise can't control, so simulating it lets you test a payout flow in a minute instead of waiting on someone else's process.

This path works on sandbox only. On production it returns 404.


Did this page help you?