Skip to main content

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​

AttributeTypeDescription
idintegerUnique numeric identifier for the beneficiary account (e.g., 12345).
accountNumberstringThe beneficiary's bank account number.
firstNamestringThe first name of the beneficiary.
lastNamestringThe last name of the beneficiary.
aliasstringA custom alias for the beneficiary account.
countryDestinationobjectAn object containing the destination country's details.
typeintegerThe type of account.
statestringThe state of the beneficiary record (e.g., active).
createdAtstringThe timestamp when the beneficiary was created (ISO 8601).

Create a Beneficiary​

POST/depositaccounts/

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

Body Parameters​

ParameterTypeDescription
accountNumberstringRequired. The beneficiary's bank account number.
firstNamestringRequired. The first name of the beneficiary.
lastNamestringRequired. The last name of the beneficiary.
countryDestinationIdintegerRequired. The ID of the destination country.
typeintegerRequired. The type of account (e.g., 0 for a standard bank account).
aliasstringOptional. A custom alias for easy identification.
emailstringOptional. The beneficiary's email address.
phonestringOptional. The beneficiary's phone number.
addressstringOptional. The beneficiary's physical address.
swiftstringOptional. The SWIFT/BIC code for international transfers.

cURL Example​

curl -X POST https://sandbox.tropipay.me/api/v3/depositaccounts/ \ 
  -H "Authorization: Bearer {your-access-token}" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "accountNumber": "ES9121000418450200051332",
    "firstName": "Jane",
    "lastName": "Doe",
    "countryDestinationId": 1,
    "type": 0,
    "alias": "Jane Doe Savings",
    "email": "jane.doe@example.com",
    "phone": "+15551234567",
    "address": "123 Main St, Anytown, USA",
    "swift": "CASHUS33XXX"
  }'

Response Example (200 OK)​

{
  "id": 12345,
  "accountNumber": "ES9121000418450200051332",
  "firstName": "Jane",
  "lastName": "Doe",
  "alias": "Jane Doe Savings",
  "state": "active",
  "createdAt": "2024-07-29T10:30:00Z"
}

List Beneficiaries​

GET/depositaccounts/

Retrieves a list of all beneficiaries associated with your account.

Query Parameters​

ParameterTypeDescription
limitintegerOptional. The maximum number of beneficiaries to return. Defaults to 10.
offsetintegerOptional. The number of beneficiaries to skip for pagination.
searchstringOptional. A search term to filter beneficiaries by name, last name, or email.

cURL Example​

curl -X GET "https://sandbox.tropipay.me/api/v3/depositaccounts/?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/depositaccounts/{beneficiaryId}

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

Path Parameters​

ParameterTypeDescription
beneficiaryIdintegerRequired. 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/depositaccounts/

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

Body Parameters​

ParameterTypeDescription
idintegerRequired. The numeric ID of the beneficiary to update.
aliasstringOptional. The new alias for the beneficiary account.

cURL Example​

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

Delete a Beneficiary​

DELETE/depositaccounts/{beneficiaryId}

Deletes a beneficiary record by their unique ID.

Path Parameters​

ParameterTypeDescription
beneficiaryIdintegerRequired. The numeric ID of the beneficiary to delete (e.g., 12345).

Body Parameters​

ParameterTypeDescription
securityCodestringRequired. The security code for authentication (e.g., 123456).

cURL Example​

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

Validate an Account Number​

POST/depositaccounts/validateaccountnumber

Validates a bank account number to check its format and existence before creating a beneficiary.

Body Parameters​

ParameterTypeDescription
accountNumberstringRequired. The account number to validate.
countryDestinationIdintegerRequired. The ID of the destination country.
typeintegerRequired. The type of account.
currencystringRequired. The currency associated with the account (e.g., USD).
paymentTypeintegerRequired. The type of payment.

cURL Example​

curl -X POST https://sandbox.tropipay.me/api/v3/depositaccounts/validateaccountnumber \ 
  -H "Authorization: Bearer {your-access-token}" \ 
  -H "Content-Type: application/json" \ 
  -d '{
    "accountNumber": "ES9121000418450200051332",
    "countryDestinationId": 1,
    "type": 0,
    "currency": "EUR",
    "paymentType": 2
  }'

Response Example (200 OK)​

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