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 Currencies & Payment Methods.

📘
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)
`belongsToBeneficiary`	boolean	Whether the recipient belongs to the beneficiary

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})?$`)
`bankName`	string	Yes	Name of the recipient bank
`bankAddress`	object	Yes	Bank address object (see address structure above). `country` must not be `US`
`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}$`
`routingNumber`	string	No	Routing number. 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
`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)
`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

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)
`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 ETH and TRON. The details object requires only walletAddress.

Field	Type	Required	Description
`walletAddress`	string	Yes	Wallet address for the rail

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": "ETH",
  "details": {
    "walletAddress": "{{WALLET_ADDRESS}}"
  }
}'

Next steps

Get the Integrator ID

Get your integrator ID.

Manage Beneficiaries

Manage your beneficiaries.

Create Virtual Accounts

Manage your virtual accounts.