Beneficiaries

The Beneficiaries API allows you to manage the recipient accounts for your transfers. You can create, list, update, and delete beneficiary records, as well as validate account details before sending funds.

The Beneficiary Object

A Beneficiary object, also referred to as a DepositAccount, stores information about a recipient, including their bank account details, name, and contact information.

Attributes

Attribute	Type	Description
`id`	integer	Unique numeric identifier for the beneficiary account (e.g., `12345`).
`accountNumber`	string	The beneficiary's bank account number.
`firstName`	string	The first name of the beneficiary.
`lastName`	string	The last name of the beneficiary.
`alias`	string	A custom alias for the beneficiary account.
`countryDestination`	object	An object containing the destination country's details.
`type`	integer	The type of account.
`state`	string	The state of the beneficiary record (e.g., `active`).
`createdAt`	string	The timestamp when the beneficiary was created (ISO 8601).

Create a Beneficiary

POST/deposit_accounts/

Creates a new beneficiary record (deposit account) to be used for future transfers.

Important Notes

Use countryISO (e.g., "ES") instead of countryDestinationId for better compatibility
paymentType must be a string (e.g., "2" for bank deposits, not integer 2)
beneficiaryType: 2 is for external bank accounts (SEPA/International)
The swift field is optional for SEPA zone countries but required for non-SEPA international transfers

Body Parameters

Parameter	Type	Description
`accountNumber`	string	Required. The beneficiary's bank account number (IBAN format for SEPA).
`firstName`	string	Required. The first name of the beneficiary.
`lastName`	string	Required. The last name of the beneficiary.
`countryISO`	string	Required. The ISO 3166-1 alpha-2 country code (e.g., `ES` for Spain, `US` for USA).
`beneficiaryType`	integer	Required. The type of beneficiary: `2` = External (bank account), `3` = Crypto.
`userRelationTypeId`	integer	Required. Relationship type: `0` = Myself, `1` = Spouse, `2` = Family, `3` = Friend, `4` = Business partner.
`paymentType`	string	Required. Payment method: `"2"` = Bank deposit (SEPA/International), `"100"` = Crypto.
`currency`	string	Required. The currency code (e.g., `EUR`, `USD`).
`city`	string	Required. The beneficiary's city.
`province`	string	Required. The beneficiary's province/state.
`address`	string	Required. The beneficiary's physical address.
`postalCode`	string	Required. The beneficiary's postal code.
`alias`	string	Optional. A custom alias for easy identification.
`email`	string	Optional. The beneficiary's email address.
`phone`	string	Optional. The beneficiary's phone number.
`swift`	string	Optional. The SWIFT/BIC code (required for non-SEPA international transfers).

cURL Example

curl -X POST https://sandbox.tropipay.me/api/v3/deposit_accounts \ 
  -H "Accept: application/json" \ 
  -H "Authorization: Bearer {your-access-token}" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "beneficiaryType": 2,
    "paymentType": "2",
    "accountNumber": "ES9121000418450200051332",
    "firstName": "Jane",
    "lastName": "Doe",
    "address": "123 Main St, Madrid, Spain",
    "city": "Madrid",
    "province": "Madrid",
    "postalCode": "28001",
    "countryISO": "ES",
    "currency": "EUR",
    "alias": "Jane Doe Savings",
    "email": "jane.doe@example.com",
    "phone": "+34912345678",
    "swift": "CAIXESBBXXX",
    "userRelationTypeId": 3
  }'

Response Example (200 OK)

{
  "id": 73604,
  "accountNumber": "ES91 2100 0418 4502 0005 1332",
  "firstName": "Jane",
  "lastName": "Doe",
  "alias": "Jane Doe Savings",
  "beneficiaryType": 2,
  "paymentType": 2,
  "currency": "EUR",
  "countryDestinationId": 1,
  "userRelationTypeId": 3,
  "city": "Madrid",
  "province": "Madrid",
  "postalCode": "28001",
  "address": "123 Main St, Madrid, Spain",
  "phone": "+34912345678",
  "swift": "CAIXESBBXXX",
  "state": 0,
  "checked": true,
  "createdAt": "2026-07-17T17:58:11.610Z",
  "updatedAt": "2026-07-17T17:58:11.610Z"
}

List Beneficiaries

GET/deposit_accounts/

Retrieves a list of all beneficiaries associated with your account.

Query Parameters

Parameter	Type	Description
`limit`	integer	Optional. The maximum number of beneficiaries to return. Defaults to 10.
`offset`	integer	Optional. The number of beneficiaries to skip for pagination.
`search`	string	Optional. A search term to filter beneficiaries by name, last name, or email.

cURL Example

curl -X GET "https://sandbox.tropipay.me/api/v3/deposit_accounts/?limit=10&search=Jane" \ 
  -H "Authorization: Bearer {your-access-token}"

Response Example (200 OK)

The following is an example of the response. For brevity, some fields within the countryDestination object and other less common attributes have been omitted.

{
  "items": [
    {
      "id": 12345,
      "accountNumber": "ES0012345678901234567890",
      "alias": "John Doe's Savings",
      "swift": "CASHESMMXXX",
      "type": 7,
      "personType": 1,
      "firstName": "John",
      "lastName": "Doe",
      "state": 0,
      "countryDestinationId": 1,
      "documentNumber": "X1234567Z",
      "address": "123 Fictional Street, Madrid",
      "phone": "600123456",
      "email": "john.doe@example.com",
      "createdAt": "2023-01-15T10:00:00.000Z",
      "updatedAt": "2023-01-15T10:00:00.000Z",
      "countryDestination": {
        "id": 1,
        "name": "España",
        "sepaZone": true,
        "slug": "ES",
        "callingCode": 34
      },
      "allowed": true
    }
  ]
}

Get a Specific Beneficiary

GET/deposit_accounts/{beneficiaryId}

Retrieves the details of a single beneficiary by their unique ID.

Path Parameters

Parameter	Type	Description
`beneficiaryId`	integer	Required. The numeric ID of the beneficiary to retrieve (e.g., `12345`).

cURL Example

curl -X GET https://sandbox.tropipay.me/api/v3/depositaccounts/12345 \ 
  -H "Authorization: Bearer {your-access-token}"

Response Example (200 OK)

{
  "id": 12345,
  "accountNumber": "ES0012345678901234567890",
  "alias": "John Doe's Savings",
  "swift": "CASHESMMXXX",
  "type": 7,
  "personType": 1,
  "firstName": "John",
  "lastName": "Doe",
  "state": 0,
  "countryDestinationId": 1,
  "documentNumber": "X1234567Z",
  "address": "123 Fictional Street, Madrid",
  "phone": "600123456",
  "email": "john.doe@example.com",
  "createdAt": "2023-01-15T10:00:00.000Z",
  "updatedAt": "2023-01-15T10:00:00.000Z",
  "countryDestination": {
    "id": 1,
    "name": "España",
    "sepaZone": true,
    "slug": "ES",
    "callingCode": 34
  },
  "paymentMethods": [
    "EXT",
    "CRYPTO",
    "APPLE_PAY",
    "GOOGLE_PAY",
    "TPP"
  ],
  "allowedAccounts": [
    {
      "id": 628,
      "alias": "Main Account",
      "currency": "EUR",
      "type": 1
    }
  ],
  "allowed": true
}

Update a Beneficiary

PUT/deposit_accounts/

Updates the alias of an existing beneficiary. Note that only the alias field can be modified through this endpoint.

Body Parameters

Parameter	Type	Description
`id`	integer	Required. The numeric ID of the beneficiary to update.
`alias`	string	Optional. The new alias for the beneficiary account.

cURL Example

curl -X PUT https://sandbox.tropipay.me/api/v3/deposit_accounts/ \ 
  -H "Authorization: Bearer {your-access-token}" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "id": 12345,
    "alias": "Jane Doe Primary Account"
  }'

Delete a Beneficiary

DELETE/deposit_accounts/{beneficiaryId}

Deletes a beneficiary record by their unique ID.

Path Parameters

Parameter	Type	Description
`beneficiaryId`	integer	Required. The numeric ID of the beneficiary to delete (e.g., `12345`).

Body Parameters

Parameter	Type	Description
`securityCode`	string	Required. The security code for authentication (e.g., `123456`).

cURL Example

curl -X DELETE https://sandbox.tropipay.me/api/v3/deposit_accounts/12345 \
  -H "Authorization: Bearer {your-access-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "securityCode": "123456"
  }'

Validate an Account Number

POST/deposit_accounts/validate_account_number

Validates an account number (bank account number or crypto wallet address) before creating a beneficiary.

Authentication: UserPrivate (requires Authorization: Bearer <token>)

Body Parameters

Field	Type	Required	Notes
`accountNumber`	`string`	Yes	Wallet address
`paymentType`	`number`	Yes	Must be `100` for crypto
`currency`	`string`	No	Token ticker, e.g. `usdc`, `usdt`
`network`	`string`	No	Blockchain network (see table below). Defaults to `SOLANA` if omitted
`countryDestinationId`	`number`	No	Use `0` for crypto

cURL Example

curl -X POST https://sandbox.tropipay.me/api/v3/deposit_accounts/validate_account_number \
  -H "Authorization: Bearer {your-access-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "paymentType": 100,
    "currency": "usdc",
    "countryDestinationId": 0
  }'

Success response `200`

{ "valid": true, "type": null, "errorCode": null }

Failure response `200`

{ "valid": false, "type": null, "errorCode": "INVALID_CRYPTO_ACOUNT" }

Note: the endpoint always returns HTTP 200. Validity is communicated via the valid field.

Create a Crypto Beneficiary Wallet

POST/deposit_accounts/

Creates a beneficiary for crypto payouts (a wallet address).

Body Parameters

Field	Type	Required	Notes
`accountNumber`	`string`	Yes	Wallet address
`paymentType`	`number`	Yes	Must be `100` for crypto
`currency`	`string`	No	Token ticker, e.g. `usdc`, `usdt`
`network`	`string`	No	Blockchain network (see table below). Defaults to `SOLANA` if omitted
`countryDestinationId`	`number`	No	Use `0` for crypto
`firstName`	`string`	Yes	Beneficiary first name
`lastName`	`string`	Yes	Beneficiary last name
`alias`	`string`	No	Friendly label

Supported Networks & Address Formats

The network field (case-insensitive) determines which validator runs.

`network` value(s)	Address format	Supported currencies
`SOLANA`	Base58, 32–44 chars	USDC, USDT, EURC, SOL, WSOL, BONK, RAY, SRM
`ETHEREUM`, `POLYGON`, `BSC`, `BINANCE_SMART_CHAIN`, `BEP20`, `ARBITRUM`, `OPTIMISM`, `AVALANCHE`, `BASE`	`0x` + 40 hex chars	USDC, USDT
`TRON`	`T` + 33 alphanumeric (34 chars total)	Any
`BINANCE_CHAIN`, `BEP2`	`bnb` + 39 lowercase alphanumeric (42 chars total)	Any
`BITCOIN`, `BTC`	Legacy `1…`/`3…` (26–35 chars) or Bech32 `bc1…` (42–62 chars)	Any
(unsupported)	Basic length check	20–100 chars

Default: if network is omitted or empty, SOLANA is used.

Example Requests

EVM address (must include `network`)

{
  "accountNumber": "0xA1b2C3d4E5f67890aBcDEF1234567890aBCdEf12",
  "paymentType": 100,
  "currency": "usdc",
  "network": "ETHEREUM",
  "countryDestinationId": 0
}

Solana address (network optional, defaults to SOLANA)

{
  "accountNumber": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "paymentType": 100,
  "currency": "usdc",
  "countryDestinationId": 0
}

EVM address without `network` field — fails

{
  "accountNumber": "0xA1b2C3d4E5f67890aBcDEF1234567890aBCdEf12",
  "paymentType": 100,
  "currency": "usdc",
  "countryDestinationId": 0
}

The Beneficiary Object​

Attributes​

Create a Beneficiary​

Body Parameters​

cURL Example​

Response Example (200 OK)​

List Beneficiaries​

Query Parameters​

cURL Example​

Response Example (200 OK)​

Get a Specific Beneficiary​

Path Parameters​

cURL Example​

Response Example (200 OK)​

Update a Beneficiary​

Body Parameters​

cURL Example​

Delete a Beneficiary​

Path Parameters​

Body Parameters​

cURL Example​

Validate an Account Number​

Body Parameters​

cURL Example​

Success response 200​

Failure response 200​

Create a Crypto Beneficiary Wallet​

Body Parameters​

Supported Networks & Address Formats​

Example Requests​

EVM address (must include network)​

Solana address (network optional, defaults to SOLANA)​

EVM address without network field — fails​

The Beneficiary Object

Attributes

Create a Beneficiary

Body Parameters

cURL Example

Response Example (200 OK)

List Beneficiaries

Query Parameters

cURL Example

Response Example (200 OK)

Get a Specific Beneficiary

Path Parameters

cURL Example

Response Example (200 OK)

Update a Beneficiary

Body Parameters

cURL Example

Delete a Beneficiary

Path Parameters

Body Parameters

cURL Example

Validate an Account Number

Body Parameters

cURL Example

Success response `200`

Failure response `200`

Create a Crypto Beneficiary Wallet

Body Parameters

Supported Networks & Address Formats

Example Requests

EVM address (must include `network`)

Solana address (network optional, defaults to SOLANA)

EVM address without `network` field — fails