Beneficiarios

La API de Beneficiarios te permite gestionar las cuentas de destinatario para tus transferencias. Puedes crear, listar, actualizar y eliminar registros de beneficiarios, así como validar los detalles de la cuenta antes de enviar fondos.

El objeto Beneficiary

Un objeto Beneficiary, también referido como DepositAccount, almacena información sobre un destinatario, incluyendo sus datos bancarios, nombre e información de contacto.

Atributos

Atributo	Tipo	Descripción
`id`	integer	Identificador numérico único para la cuenta beneficiaria (por ejemplo, `12345`).
`accountNumber`	string	El número de cuenta bancaria del beneficiario.
`firstName`	string	El nombre del beneficiario.
`lastName`	string	El apellido del beneficiario.
`alias`	string	Un alias personalizado para la cuenta del beneficiario.
`countryDestination`	object	Un objeto que contiene los detalles del país de destino.
`type`	integer	El tipo de cuenta.
`state`	string	El estado del registro del beneficiario (por ejemplo, `active`).
`createdAt`	string	La marca temporal de creación del beneficiario (ISO 8601).

Crear un beneficiario

POST/deposit_accounts/

Crea un nuevo registro de beneficiario (cuenta de depósito) para usar en transferencias futuras.

Notas importantes

Usa countryISO (por ejemplo, "ES") en lugar de countryDestinationId para mayor compatibilidad
paymentType debe ser un string (por ejemplo, "2" para depósitos bancarios, no el entero 2)
beneficiaryType: 2 es para cuentas bancarias externas (SEPA/Internacional)
El campo swift es opcional para países de la zona SEPA, pero requerido para transferencias internacionales fuera de SEPA

Parámetros del cuerpo

Parámetro	Tipo	Descripción
`accountNumber`	string	Requerido. El número de cuenta bancaria del beneficiario (formato IBAN para SEPA).
`firstName`	string	Requerido. El nombre del beneficiario.
`lastName`	string	Requerido. El apellido del beneficiario.
`countryISO`	string	Requerido. El código de país ISO 3166-1 alpha-2 (por ejemplo, `ES` para España, `US` para EE. UU.).
`beneficiaryType`	integer	Requerido. El tipo de beneficiario: `2` = Externa (cuenta bancaria), `3` = Cripto.
`userRelationTypeId`	integer	Requerido. Tipo de relación: `0` = Yo mismo, `1` = Cónyuge, `2` = Familia, `3` = Amigo, `4` = Socio comercial.
`paymentType`	string	Requerido. Método de pago: `"2"` = Depósito bancario (SEPA/Internacional), `"100"` = Cripto.
`currency`	string	Requerido. El código de moneda (por ejemplo, `EUR`, `USD`).
`city`	string	Requerido. La ciudad del beneficiario.
`province`	string	Requerido. La provincia/estado del beneficiario.
`address`	string	Requerido. La dirección física del beneficiario.
`postalCode`	string	Requerido. El código postal del beneficiario.
`alias`	string	Opcional. Un alias personalizado para fácil identificación.
`email`	string	Opcional. El correo electrónico del beneficiario.
`phone`	string	Opcional. El número de teléfono del beneficiario.
`swift`	string	Opcional. El código SWIFT/BIC (requerido para transferencias internacionales fuera de SEPA).

Ejemplo de cURL

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
  }'

Ejemplo de respuesta (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"
}

Listar beneficiarios

GET/deposit_accounts/

Recupera una lista de todos los beneficiarios asociados a tu cuenta.

Parámetros de consulta

Parámetro	Tipo	Descripción
`limit`	integer	Opcional. El número máximo de beneficiarios a devolver. Por defecto 10.
`offset`	integer	Opcional. El número de beneficiarios a omitir para la paginación.
`search`	string	Opcional. Un término de búsqueda para filtrar beneficiarios por nombre, apellido o correo electrónico.

Ejemplo de cURL

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

Ejemplo de respuesta (200 OK)

Lo siguiente es un ejemplo de la respuesta. Por brevedad, se han omitido algunos campos dentro del objeto countryDestination y otros atributos menos comunes.

{
  "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
    }
  ]
}

Obtener un beneficiario específico

GET/deposit_accounts/{beneficiaryId}

Recupera los detalles de un único beneficiario por su ID único.

Parámetros de ruta

Parámetro	Tipo	Descripción
`beneficiaryId`	integer	Requerido. El ID numérico del beneficiario a recuperar (por ejemplo, `12345`).

Ejemplo de cURL

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

Ejemplo de respuesta (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
}

Actualizar un beneficiario

PUT/deposit_accounts/

Actualiza el alias de un beneficiario existente. Ten en cuenta que solo el campo alias puede modificarse a través de este endpoint.

Parámetros del cuerpo

Parámetro	Tipo	Descripción
`id`	integer	Requerido. El ID numérico del beneficiario a actualizar.
`alias`	string	Opcional. El nuevo alias para la cuenta del beneficiario.

Ejemplo de cURL

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"
  }'

Eliminar un beneficiario

DELETE/deposit_accounts/{beneficiaryId}

Elimina un registro de beneficiario por su ID único.

Parámetros de ruta

Parámetro	Tipo	Descripción
`beneficiaryId`	integer	Requerido. El ID numérico del beneficiario a eliminar (por ejemplo, `12345`).

Parámetros del cuerpo

Parámetro	Tipo	Descripción
`securityCode`	string	Requerido. El código de seguridad para autenticación (por ejemplo, `123456`).

Ejemplo de cURL

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"
  }'

Validar un número de cuenta

POST/deposit_accounts/validate_account_number

Valida un número de cuenta (número de cuenta bancaria o dirección de billetera crypto) antes de crear un beneficiario.

Autenticación: UserPrivate (requiere Authorization: Bearer <token>)

Parámetros del cuerpo

Campo	Tipo	Requerido	Notas
`accountNumber`	`string`	Sí	Dirección de billetera
`paymentType`	`number`	Sí	Debe ser `100` para crypto
`currency`	`string`	No	Ticker del token, por ejemplo `usdc`, `usdt`
`network`	`string`	No	Red blockchain (ver tabla abajo). Por defecto `SOLANA` si se omite
`countryDestinationId`	`number`	No	Usa `0` para crypto

Ejemplo de cURL

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
  }'

Respuesta exitosa `200`

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

Respuesta fallida `200`

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

Nota: el endpoint siempre devuelve HTTP 200. La validez se comunica a través del campo valid.

Crear una billetera de beneficiario crypto

POST/deposit_accounts/

Crea un beneficiario para pagos de retiro de cripto (una dirección de billetera).

Parámetros del cuerpo

Campo	Tipo	Requerido	Notas
`accountNumber`	`string`	Sí	Dirección de billetera
`paymentType`	`number`	Sí	Debe ser `100` para crypto
`currency`	`string`	No	Ticker del token, por ejemplo `usdc`, `usdt`
`network`	`string`	No	Red blockchain (ver tabla abajo). Por defecto `SOLANA` si se omite
`countryDestinationId`	`number`	No	Usa `0` para crypto
`firstName`	`string`	Sí	Nombre del beneficiario
`lastName`	`string`	Sí	Apellido del beneficiario
`alias`	`string`	No	Etiqueta descriptiva

Redes soportadas y formatos de dirección

El campo network (insensible a mayúsculas) determina qué validador se ejecuta.

Valor(es) de `network`	Formato de dirección	Criptomonedas soportadas
`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) o Bech32 `bc1…` (42–62 chars)	Any
(no soportada)	Basic length check	20–100 chars

Por defecto: si network se omite o está vacío, se usa SOLANA.

Ejemplos de solicitudes

Dirección EVM (debe incluir `network`)

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

Dirección Solana (network opcional, por defecto SOLANA)

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

Dirección EVM sin el campo `network` — falla

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

El objeto Beneficiary​

Atributos​

Crear un beneficiario​

Parámetros del cuerpo​

Ejemplo de cURL​

Ejemplo de respuesta (200 OK)​

Listar beneficiarios​

Parámetros de consulta​

Ejemplo de cURL​

Ejemplo de respuesta (200 OK)​

Obtener un beneficiario específico​

Parámetros de ruta​

Ejemplo de cURL​

Ejemplo de respuesta (200 OK)​

Actualizar un beneficiario​

Parámetros del cuerpo​

Ejemplo de cURL​

Eliminar un beneficiario​

Parámetros de ruta​

Parámetros del cuerpo​

Ejemplo de cURL​

Validar un número de cuenta​

Parámetros del cuerpo​

Ejemplo de cURL​

Respuesta exitosa 200​

Respuesta fallida 200​

Crear una billetera de beneficiario crypto​

Parámetros del cuerpo​

Redes soportadas y formatos de dirección​

Ejemplos de solicitudes​

Dirección EVM (debe incluir network)​

Dirección Solana (network opcional, por defecto SOLANA)​

Dirección EVM sin el campo network — falla​

El objeto Beneficiary

Atributos

Crear un beneficiario

Parámetros del cuerpo

Ejemplo de cURL

Ejemplo de respuesta (200 OK)

Listar beneficiarios

Parámetros de consulta

Ejemplo de cURL

Ejemplo de respuesta (200 OK)

Obtener un beneficiario específico

Parámetros de ruta

Ejemplo de cURL

Ejemplo de respuesta (200 OK)

Actualizar un beneficiario

Parámetros del cuerpo

Ejemplo de cURL

Eliminar un beneficiario

Parámetros de ruta

Parámetros del cuerpo

Ejemplo de cURL

Validar un número de cuenta

Parámetros del cuerpo

Ejemplo de cURL

Respuesta exitosa `200`

Respuesta fallida `200`

Crear una billetera de beneficiario crypto

Parámetros del cuerpo

Redes soportadas y formatos de dirección

Ejemplos de solicitudes

Dirección EVM (debe incluir `network`)

Dirección Solana (network opcional, por defecto SOLANA)

Dirección EVM sin el campo `network` — falla