ALalfredpay
Linked Accounts

Register a recipient on your own account

Changed on

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.

CountryidentifierTypesupportedRails[]
MEXCLABE[SPEI]
ARGCBU or CVU, 22 digits[COELSA]
BRAPIX_KEY, with pixKeyType[PIX]
USAROUTING_AND_ACCOUNT or ACCOUNT_NUMBER[ACH]
COLACCOUNT_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.

post/v1/linked_accounts

Request

  • Base URL
    https://api.sandbox.alfredpay.io
  • URL
    https://api.sandbox.alfredpay.io/v1/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).

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.

holderNamestring

The account holder's legal name. Required for BANK_ACCOUNT, omitted for WALLET.

holderTaxIdstring

The holder's tax ID, such as a CUIT in Argentina. Send it whenever you have it.

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

Required for WALLET.

Response

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

idstring

link_...

customerIdstring

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).

countrystring 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.

supportedRailsRail[]
identifierMaskedstring nullable

Last four characters only.

holderNamestring

Empty string for a wallet.

createdAtstring date-time

Changes