---
title: "Register a recipient on your own account"
method: POST
path: "/v1/linked_accounts"
tags: ["Linked Accounts"]
---

# Register a recipient on your own account

`POST /v1/linked_accounts`

## Request

- Base URL: `https://api.sandbox.alfredpay.io`
- URL: `https://api.sandbox.alfredpay.io/v1/linked_accounts`
- Auth: one of:
  - HTTP bearer
  - API key in header `api-key` and API key in header `api-secret`

Registers a bank account or wallet on your own account rather than on a customer. 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`.

`relationshipType` is required: `FIRST_PARTY` for an account or wallet you hold yourself, `THIRD_PARTY` for a beneficiary you pay.

You never name a rail. Alfred derives `supportedRails[]` from the country and the identifier type.

| Country | `identifierType` | `supportedRails[]` |
|---|---|---|
| `MEX` | `CLABE` | `[SPEI]` |
| `ARG` | `CBU` or `CVU`, 22 digits | `[COELSA]` |
| `BRA` | `PIX_KEY`, with `pixKeyType` | `[PIX]` |
| `USA` | `ROUTING_AND_ACCOUNT` or `ACCOUNT_NUMBER` | `[ACH]` |
| `COL` | `ACCOUNT_NUMBER`, with `bankCode` | `[ACH]` |

A combination with no rail, or a wallet on a chain that can't be screened, is refused with `422 route_unsupported`.

**When it can be paid.** A bank account is `VERIFIED` on creation. A wallet is `PENDING` until on-chain screening clears, normally within moments; read it back with `GET /v1/linked_accounts/{linkedAccountId}`. A payout to anything other than `VERIFIED` is refused with `recipient_not_linked`.

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- OwnLinkedAccountCreate: A recipient on your own account.
  - `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).
  - `relationshipType` 'FIRST_PARTY' | 'THIRD_PARTY', required: `FIRST_PARTY` for an account or wallet you hold yourself, `THIRD_PARTY` for a beneficiary you pay.
  - `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 account holder's legal name. Required for BANK_ACCOUNT, omitted for WALLET.
  - `holderTaxId` string: The holder's tax ID, such as a CUIT in Argentina. Send it whenever you have it.
  - `bankAccount` object: BANK_ACCOUNT only.
    - `identifierType` 'CLABE' | 'CBU' | 'CVU' | 'ALIAS' | 'PIX_KEY' | 'ACCOUNT_NUMBER' | 'ROUTING_AND_ACCOUNT' | 'IBAN' | 'PHONE', required: 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, required: The CLABE, CBU, CVU, account number or PIX key.
    - `bankCode` string: Colombia: the beneficiary's bank.
    - `bankName` string
    - `routingNumber` string: USA only, with ROUTING_AND_ACCOUNT.
    - `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.

## Response `201`

Created. A bank account returns `VERIFIED`; a wallet returns `PENDING`.

- OwnLinkedAccount
  - `id` string: link_...
  - `customerId` string: Your own account, acct_...
  - `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` string, nullable: ISO alpha-3 for a bank account, null for a wallet.
  - `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[]
  - `identifierMasked` string, nullable: Last four characters only.
  - `holderName` string: Empty string for a wallet.
  - `relationship` object
    - `relationship_type` 'FIRST_PARTY' | 'THIRD_PARTY'
    - `relationship_status` 'PENDING' | 'VERIFIED' | 'REJECTED' | 'EXPIRED' | 'REVOKED'
    - `allowed_use_cases` string[]
  - `createdAt` string, date-time

## Other responses

- `400`: Malformed request, so a missing required field, a wrong type or a bad enum.
- `401`: Missing or invalid credentials.
- `409`: `idempotency_conflict`, or the resource is in a state that forbids this call.
- `422`: `route_unsupported`: the country and identifier type have no rail, or the wallet's chain can't be screened.

## Changes

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

[Operation history](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/changes/v1/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)