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 on | Call | Paid from |
|---|---|---|
| Your own account | POST /v1/linked_accounts | Your own balance |
| A customer | POST /v1/customers/{customerId}/linked_accounts | That 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.
relationshipType | Means |
|---|---|
FIRST_PARTY | An account or wallet you hold yourself |
THIRD_PARTY | A 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"
}
}| Field | Required | Notes |
|---|---|---|
destinationType | Yes | BANK_ACCOUNT |
relationshipType | Yes | FIRST_PARTY or THIRD_PARTY |
holderType | THIRD_PARTY | INDIVIDUAL or BUSINESS. Optional on FIRST_PARTY |
country | Yes | ISO alpha-3 |
currency | Yes | ISO 4217 |
holderName | Yes | The account holder's legal name |
holderTaxId | No | The holder's tax ID, such as a CUIT in Argentina. Send it whenever you have it |
bankAccount.identifierType | Yes | See the table below |
bankAccount.identifier | Yes | The CLABE, CBU, CVU, account number or PIX key |
bankAccount.bankCode | Colombia | The beneficiary's bank, as the code from GET /v1/countries/COL/banks. See Bank codes |
bankAccount.routingNumber | United States | With ROUTING_AND_ACCOUNT |
bankAccount.pixKeyType | Brazil | CPF, CNPJ, PHONE, EMAIL or EVP |
You never name a rail. Alfred derives it from the country and the identifier type.
| Country | identifierType | supportedRails[] |
|---|---|---|
| Mexico | CLABE | [SPEI] |
| Argentina | CBU or CVU, 22 digits | [COELSA] |
| Brazil | PIX_KEY, with pixKeyType | [PIX] |
| United States | ROUTING_AND_ACCOUNT or ACCOUNT_NUMBER | [ACH] |
| Colombia | ACCOUNT_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
| Type | On creation | Can be paid |
|---|---|---|
| Bank account | relationship_status: VERIFIED | Straight away |
| Wallet | relationship_status: PENDING | Once 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"
}| Field | What it is |
|---|---|
id | The recipient's ID, link_.... Every payout to it uses this |
customerId | Your own account |
country | ISO alpha-3 for a bank account, null for a wallet |
supportedRails | The rails it can be reached on |
identifierMasked | The last four characters of the identifier |
holderName | The holder's name, and an empty string for a wallet |
relationship | relationship_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" }
]
}| Field | What it is |
|---|---|
name | The bank's name, to show in your bank picker |
code | What you send as bankAccount.bankCode |
id | Alfred'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 register | You 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_OWNERSHIPorWALLET_OWNERSHIPfor the customer's ownTHIRD_PARTY_BENEFICIARYfor 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.
| Status | Can receive a payout |
|---|---|
PENDING | No, screening is still in progress. |
VERIFIED | Yes. |
REJECTED | No. |
EXPIRED | No. |
REVOKED | No. |
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.
Updated 12 days ago

