Create Recipients

Recipients are the destination accounts to which you send payments. Create and store recipients before initiating a payment. The API returns a recipient ID that you should save and reuse.

Caliza supports the following recipient types:

Fiat rails: SWIFT (USD), ACH (USD), WIRE (USD), RTP (USD), PIX (BRL), SPEI (MXN), COP (COP), CVU (ARS).

Crypto rails: ETH, TRON.

Each type requires specific fields in the details object (see the sections below). Where a rail uses addresses, the address object has required fields street1, city, state, postalCode, and country (2-letter ISO), and optional street2; state must be a 2–3 letter ISO state code. For supported currencies and payment methods, see Coverage.

📘
Store the returned recipient ID for use in payment requests and for auditing.

To create a recipient, you need to send a POST request to the /recipients endpoint with the necessary details. See the sections below for more information on the requests of each recipient type.

Request fields

The following tables describe the fields for the RecipientRequest object.

Required fields

Field	Type	Description
`currency`	string	Currency code (e.g., `USD`, `BRL`, `MXN`)
`type`	string	Payment rail type (e.g., `SWIFT`, `ACH`, `PIX`)
`individualName` OR `businessName`	string	Exactly one must be provided
`details`	object	Payment rail–specific fields (structure varies by type; see sections below)

Conditionally required fields

Field	Type	Condition
`beneficiaryId`	string	Required for beneficiary-level recipients
`countryOfIncorporation`	string	Required when `businessName` is provided (max 2 characters)

Optional fields

Field	Type	Description
`id`	string	Unique identifier for the recipient (used for updates)
`nickname`	string	A display name for the recipient (max 50 characters; only letters, numbers, spaces, hyphens, parentheses, periods, commas, underscores, and apostrophes are allowed)
`belongsToBeneficiary`	boolean	Whether the recipient belongs to the beneficiary
`integratorRecipient`	boolean	Whether the recipient is an integrator-level recipient. Must be set to `true` for recipients used as destinations in Account Sweeps.

See the sections below for more information on the details object structure for each recipient type.

Create SWIFT recipient

SWIFT recipient details fields

The details object for SWIFT recipients can include the following fields:

Field	Type	Required	Description
`swiftCode`	string	Yes	SWIFT/BIC code of the recipient bank (8 or 11 characters; pattern: `^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$`; validated against SWIFT directory)
`bankName`	string	Yes	Name of the recipient bank
`bankAddress`	object	Yes	Bank address object (see address structure above). `country` must not be `US` — use the WIRE type for US domestic transfers
`recipientAddress`	object	Yes	Recipient address object (see address structure above)
`accountNumber` OR `iban`	string	Yes	At least one must be provided. `iban` pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$` (validated against IBAN directory)
`routingNumber`	string	No	Routing number (validated against US bank directory if provided). Use if you want to specify wire routing; otherwise Caliza determines the optimal route.
`intermediaryBankSwiftCode`	string	No	SWIFT code of intermediary bank. Use if you want to specify wire routing; otherwise Caliza determines the optimal route.
`intermediaryBankName`	string	No	Name of intermediary bank. Use if you want to specify wire routing; otherwise Caliza determines the optimal route.

Example request

To create a SWIFT recipient, use the following request:

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "businessName": "{{BUSINESS_NAME}}",
  "currency": "{{CURRENCY}}",
  "type": "SWIFT",
  "details": {
    "swiftCode": "{{SWIFT_CODE}}",
    "bankName": "{{BANK_NAME}}",
    "routingNumber": "{{ROUTING_NUMBER}}",
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "bankAddress": {
      "street1": "{{BANK_STREET1}}",
      "postalCode": "{{BANK_POSTAL_CODE}}",
      "city": "{{BANK_CITY}}",
      "state": "{{BANK_STATE}}",
      "country": "{{BANK_COUNTRY}}"
    },
    "recipientAddress": {
      "street1": "{{RECIPIENT_STREET1}}",
      "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
      "city": "{{RECIPIENT_CITY}}",
      "state": "{{RECIPIENT_STATE}}",
      "country": "{{RECIPIENT_COUNTRY}}"
    }
  }
}'

{
    "id": "{{RECIPIENT_ID}}",
    "beneficiaryId": "{{BENEFICIARY_ID}}",
    "individualName": "{{INDIVIDUAL_NAME}}",
    "businessName": "{{BUSINESS_NAME}}",
    "currency": "{{CURRENCY}}",
    "type": "SWIFT",
    "countryOfIncorporation": "{{COUNTRY_OF_INCORPORATION}}",
    "belongsToBeneficiary": true,
    "details": {
        "swiftCode": "{{SWIFT_CODE}}",
        "bankName": "{{BANK_NAME}}",
        "intermediaryBankSwiftCode": "{{INTERMEDIARY_BANK_SWIFT_CODE}}",
        "intermediaryBankName": "{{INTERMEDIARY_BANK_NAME}}",
        "routingNumber": "{{ROUTING_NUMBER}}",
        "accountNumber": "{{ACCOUNT_NUMBER}}",
        "bankAddress": {
            "street1": "{{BANK_STREET1}}",
            "postalCode": "{{BANK_POSTAL_CODE}}",
            "city": "{{BANK_CITY}}",
            "state": "{{BANK_STATE}}",
            "country": "{{BANK_COUNTRY}}"
        },
        "recipientAddress": {
            "street1": "{{RECIPIENT_STREET1}}",
            "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
            "city": "{{RECIPIENT_CITY}}",
            "state": "{{RECIPIENT_STATE}}",
            "country": "{{RECIPIENT_COUNTRY}}"
        }
    }
}

The response includes the recipient ID and other relevant information and should look like this:

Where:

id: The unique identifier for the recipient.
beneficiaryId: The ID of the beneficiary associated with the recipient.
individualName: The name of the individual associated with the recipient.
businessName: The name of the business associated with the recipient.
currency: The currency of the recipient.
type: The type of the recipient (in this case, SWIFT).
details: An object containing specific details about the SWIFT recipient, including bank information and addresses.

The SWIFT recipient has been created and is ready to send payments.

Create ACH recipient

ACH (Automated Clearing House) is supported for USD domestic transfers.

ACH recipient details fields

The details object for ACH recipients can include the following fields:

Field	Type	Required	Description
`accountNumber`	string	Yes	Account number
`routingNumber`	string	Yes	Routing number (must be exactly 9 characters; validated against US bank directory)
`bankName`	string	Yes	Name of the recipient bank
`bankCountry`	string	Yes	ISO 3166-1 alpha-2 country code of the bank (2 characters)
`accountType`	string	Yes	One of: `Checking`, `Savings`, `GeneralLedger`, `Loan`
`recipientAddress`	object	Yes	Recipient address object (see address structure above)

Example request

To create an ACH recipient, use the following request:

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "businessName": "{{BUSINESS_NAME}}",
  "currency": "{{CURRENCY}}",
  "type": "ACH",
  "details": {
    "bankName": "{{BANK_NAME}}",
    "bankCountry": "{{BANK_COUNTRY}}",
    "accountType": "Checking",
    "routingNumber": "{{ROUTING_NUMBER}}",
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "recipientAddress": {
      "street1": "{{RECIPIENT_STREET1}}",
      "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
      "city": "{{RECIPIENT_CITY}}",
      "state": "{{RECIPIENT_STATE}}",
      "country": "{{RECIPIENT_COUNTRY}}"
    }
  }
}'

{
    "id": "{{RECIPIENT_ID}}",
    "beneficiaryId": "{{BENEFICIARY_ID}}",
    "individualName": "{{INDIVIDUAL_NAME}}",
    "businessName": {{BUSINESS_NAME}},
    "currency": "{{CURRENCY}}",
    "type": "ACH",
    "countryOfIncorporation": "{{COUNTRY_OF_INCORPORATION}}",
    "belongsToBeneficiary": true,
    "details": {
        "bankName": "{{BANK_NAME}}",
        "bankCountry": "{{BANK_COUNTRY}}",
        "accountType": "Checking",
        "routingNumber": "{{ROUTING_NUMBER}}",
        "accountNumber": "{{ACCOUNT_NUMBER}}",
        "recipientAddress": {
            "street1": "{{RECIPIENT_STREET1}}",
            "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
            "city": "{{RECIPIENT_CITY}}",
            "state": "{{RECIPIENT_STATE}}",
            "country": "{{RECIPIENT_COUNTRY}}"
        }
    }
}

The response includes the recipient ID and other relevant information.

Where:

id: The unique identifier for the recipient.
beneficiaryId: The ID of the beneficiary associated with the recipient.
individualName: The name of the individual associated with the recipient.
businessName: The name of the business associated with the recipient.
currency: The currency of the recipient.
type: The type of the recipient (in this case, ACH).
details: An object containing specific details about the ACH recipient, including bank information and addresses.

The ACH recipient has been created and is ready to send payments.

Create a WIRE recipient

WIRE recipient details fields

The details object for WIRE recipients can include the following fields:

Field	Type	Required	Description
`accountNumber`	string	Yes	Account number
`routingNumber`	string	Yes	Routing number (must be exactly 9 characters; validated against US bank directory)
`bankName`	string	Yes	Name of the recipient bank
`bankAddress`	object	Yes	Bank address object (see address structure above)
`recipientAddress`	object	Yes	Recipient address object (see address structure above)

Example request

To create a WIRE recipient, use the following request:

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "{{CURRENCY}}",
  "type": "WIRE",
  "details": {
    "bankName": "{{BANK_NAME}}",
    "routingNumber": "{{ROUTING_NUMBER}}",
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "bankAddress": {
      "street1": "{{BANK_STREET1}}",
      "postalCode": "{{BANK_POSTAL_CODE}}",
      "city": "{{BANK_CITY}}",
      "state": "{{BANK_STATE}}",
      "country": "{{BANK_COUNTRY}}"
    },
    "recipientAddress": {
      "street1": "{{RECIPIENT_STREET1}}",
      "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
      "city": "{{RECIPIENT_CITY}}",
      "state": "{{RECIPIENT_STATE}}",
      "country": "{{RECIPIENT_COUNTRY}}"
    }
  }
}'

{
    "id": "{{RECIPIENT_ID}}",
    "beneficiaryId": "{{BENEFICIARY_ID}}",
    "individualName": "{{INDIVIDUAL_NAME}}",
    "businessName": "{{BUSINESS_NAME}}",
    "currency": "{{CURRENCY}}",
    "type": "WIRE",
    "countryOfIncorporation": "{{COUNTRY_OF_INCORPORATION}}",
    "belongsToBeneficiary": true,
    "details": {
        "bankName": "{{BANK_NAME}}",
        "routingNumber": "{{ROUTING_NUMBER}}",
        "accountNumber": "{{ACCOUNT_NUMBER}}",
        "bankAddress": {
            "street1": "{{BANK_STREET1}}",
            "postalCode": "{{BANK_POSTAL_CODE}}",
            "city": "{{BANK_CITY}}",
            "state": "{{BANK_STATE}}",
            "country": "{{BANK_COUNTRY}}"
        },
        "recipientAddress": {
            "street1": "{{RECIPIENT_STREET1}}",
            "postalCode": "{{RECIPIENT_POSTAL_CODE}}",
            "city": "{{RECIPIENT_CITY}}",
            "state": "{{RECIPIENT_STATE}}",
            "country": "{{RECIPIENT_COUNTRY}}"
        }
    }
}

The response includes the recipient ID and other relevant information.

Where:

id: The unique identifier for the recipient.
beneficiaryId: The ID of the beneficiary associated with the recipient.
individualName: The name of the individual associated with the recipient.
businessName: The name of the business associated with the recipient.
currency: The currency of the recipient.
type: The type of the recipient (in this case, WIRE).
details: An object containing specific details about the WIRE recipient, including bank information and addresses.

The WIRE recipient has been created and is ready to send payments.

Create RTP recipient

RTP (Real-Time Payments) is supported for USD. The details object requires only accountNumber and routingNumber; no address fields.

Field	Type	Required	Description
`accountNumber`	string	Yes	Account number
`routingNumber`	string	Yes	Routing number (must be exactly 9 characters)

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "USD",
  "type": "RTP",
  "details": {
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "routingNumber": "{{ROUTING_NUMBER}}"
  }
}'

Create PIX recipient

PIX is supported for BRL. The details object requires pixKey and documentNumber. documentNumber must be 11 characters (CPF) or 14 characters (CNPJ) after removing /, -, and ..

Field	Type	Required	Description
`pixKey`	string	Yes	PIX key
`documentNumber`	string	Yes	CPF (11 chars) or CNPJ (14 chars), without formatting characters

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "BRL",
  "type": "PIX",
  "details": {
    "pixKey": "{{PIX_KEY}}",
    "documentNumber": "{{DOCUMENT_NUMBER}}"
  }
}'

Create SPEI recipient

SPEI is supported for MXN. The details object requires clabe, bankCode, and receiverName; no optional details fields.

Field	Type	Required	Description
`clabe`	string	Yes	CLABE (Clave Bancaria Estandarizada). Must be exactly 18 digits with a valid check digit
`bankCode`	string	Yes	Bank code
`receiverName`	string	Yes	Name of the receiver

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "MXN",
  "type": "SPEI",
  "details": {
    "clabe": "{{CLABE}}",
    "bankCode": "{{BANK_CODE}}",
    "receiverName": "{{RECEIVER_NAME}}"
  }
}'

Create COP recipient

COP is supported for Colombian peso transfers. The details object requires accountType (one of CHECKING, SAVINGS), bankAccount, and bankCode. If thirdPartyWithdrawal is true, you must also provide documentId, documentType, and email.

Field	Type	Required	Description
`accountType`	string	Yes	One of: `CHECKING`, `SAVINGS`
`bankAccount`	string	Yes	Bank account number
`bankCode`	string	Yes	Bank code
`thirdPartyWithdrawal`	boolean	No	Default `false`. If `true`, `documentId`, `documentType`, and `email` are required
`documentId`	string	Conditionally	Required when `thirdPartyWithdrawal` is true
`documentType`	string	Conditionally	Required when `thirdPartyWithdrawal` is true
`email`	string	Conditionally	Required when `thirdPartyWithdrawal` is true

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "COP",
  "type": "COP",
  "details": {
    "accountType": "SAVINGS",
    "bankAccount": "{{BANK_ACCOUNT}}",
    "bankCode": "{{BANK_CODE}}"
  }
}'

Create CVU recipient

CVU (Argentine virtual uniform key) is supported for ARS. The details object requires recipientName and cvu; no optional details fields.

Field	Type	Required	Description
`recipientName`	string	Yes	Name of the recipient
`cvu`	string	Yes	CVU identifier

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "ARS",
  "type": "CVU",
  "details": {
    "recipientName": "{{RECIPIENT_NAME}}",
    "cvu": "{{CVU}}"
  }
}'

Create crypto recipient

Crypto recipients are supported for the following rail/currency combinations:

Rail (`type`)	Currency
`ETH`	`USDC`
`TRON`	`USDT`

To comply with the crypto Travel Rule, every crypto recipient must declare where the destination wallet is hosted: either at a VASP (a crypto exchange or custodial wallet provider) or as a self-hosted wallet (a non-custodial wallet such as MetaMask or a hardware wallet, where the holder controls the private keys).

The details object accepts the following fields:

Field	Type	Required	Description
`walletAddress`	string	Yes	Wallet address for the rail
`vaspId`	string	Conditional	Identifier of the VASP hosting the wallet, from Search the VASP directory.
`isNonCustodialWallet`	boolean	Conditional	Set to `true` when the wallet is self-hosted (non-custodial).
`vaspName`	string	No	Optional free-text name of the hosting provider, for display purposes. Not sufficient on its own — a `vaspId` or `isNonCustodialWallet: true` is still required.
`recipientAddress`	object	Conditional	Physical address of the recipient. Required for self-hosted wallets that belong to a third party (`belongsToBeneficiary: false`), with at least `streetOne`, `city`, and `country`.

One of vaspId or isNonCustodialWallet: true must be provided.

Wallet hosted at a VASP

Find the VASP with Search the VASP directory and pass its id as vaspId. If the provider is not listed in the directory, contact Caliza support — a free-text vaspName alone is not accepted, because the Travel Rule message could not be addressed to the provider.

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "USDC",
  "type": "ETH",
  "details": {
    "walletAddress": "{{WALLET_ADDRESS}}",
    "vaspId": "{{VASP_ID}}"
  }
}'

Self-hosted wallet

For a self-hosted wallet, set isNonCustodialWallet: true. When the wallet belongs to someone other than the beneficiary (belongsToBeneficiary: false), the recipient's physical address is also required:

curl --location --request POST 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "USDT",
  "type": "TRON",
  "details": {
    "walletAddress": "{{WALLET_ADDRESS}}",
    "isNonCustodialWallet": true,
    "recipientAddress": {
      "streetOne": "123 Main St",
      "city": "Miami",
      "state": "FL",
      "postalCode": "33101",
      "country": "US"
    }
  }
}'

Review status

Every crypto recipient is created with reviewStatus: PENDING_REVIEW and screened immediately. A clean screening approves it automatically (APPROVED), usually within seconds. When the declared hosting contradicts on-chain attribution data — for example a wallet declared self-hosted that is attributed to an exchange — the recipient stays PENDING_REVIEW until a compliance reviewer approves or rejects it. Simulations and transactions targeting a recipient in PENDING_REVIEW or REJECTED fail with HTTP 422 and error code recipient.under_review.

🔐
Before you can send payouts to a self-hosted wallet recipient, a wallet ownership proof must be collected for its address — see Self-Hosted Wallets. Updating a recipient's wallet or Travel Rule details invalidates previously collected proofs, requiring a new one.

Next steps

Get the Integrator ID

Get your integrator ID.

Manage Beneficiaries

Manage your beneficiaries.

Create Virtual Accounts

Manage your virtual accounts.