Cuentas

La API de Cuentas te permite gestionar las cuentas de usuario, incluyendo la recuperación de información de cuentas, consulta de saldos, conversión de monedas y gestión de integraciones con Tropicard.

El objeto Account

{
    "id": 21221,
    "accountNumber": "TP00-0000-0000-0000-0000",
    "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "alias": "My Account",
    "balance": 418090,
    "pendingIn": 1422276,
    "pendingOut": 0,
    "state": 1,
    "paymentEntityId": 34,
    "currency": "USDC",
    "type": 1,
    "createdAt": "2025-07-14T19:10:04.936Z",
    "updatedAt": "2025-07-22T13:16:59.737Z",
    "isDefault": false,
    "groupId": null,
    "TropiCards": [],
    "services": [
        {
            "slug": "CRYPTO_TOPUP",
            "enabled": true
        }
    ],
    "paymentMethods": [
        {
            "slug": "TPP",
            "name": "Tropipay",
            "enabled": true
        }
    ]
}

Atributos

Atributo	Tipo	Descripción
id	integer	Identificador único de la cuenta.
accountNumber	string	El número de cuenta único.
userId	string	El ID del usuario propietario de la cuenta.
alias	string	Un nombre definido por el usuario para la cuenta.
balance	integer	El saldo actual de la cuenta en céntimos.
pendingIn	integer	El monto de fondos entrantes pendientes de confirmación, en céntimos.
pendingOut	integer	El monto de fondos salientes pendientes de confirmación, en céntimos.
state	integer	El estado de la cuenta (por ejemplo, 1 para activa).
currency	string	El código de moneda de la cuenta (por ejemplo, USDC, EUR).
type	integer	El tipo de cuenta (por ejemplo, 1 para una cuenta estándar).
createdAt	string	La fecha y hora de creación de la cuenta, en formato ISO 8601.
updatedAt	string	La fecha y hora de la última actualización de la cuenta, en formato ISO 8601.
isDefault	boolean	Indica si esta es la cuenta predeterminada del usuario.
services	array	Una lista de servicios financieros habilitados para esta cuenta.
paymentMethods	array	Una lista de métodos de pago disponibles para esta cuenta.

Listar todas las cuentas

Devuelve una lista de todas las cuentas asociadas al usuario autenticado.

GET/accounts/

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/ \
  -H "Authorization: Bearer sk_test_..."

Parámetros

Parámetro	Tipo	Requerido	Descripción
type	string	No	Filtrar por tipo de cuenta

Respuesta

[
  {
    "id": 21221,
    "accountNumber": "TP00-0000-0000-0000-0000",
    "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "alias": "My Account",
    "balance": 418090,
    "pendingIn": 1422276,
    "pendingOut": 0,
    "state": 1,
    "paymentEntityId": 34,
    "currency": "USDC",
    "type": 1,
    "createdAt": "2025-07-14T19:10:04.936Z",
    "updatedAt": "2025-07-22T13:16:59.737Z",
    "isDefault": false,
    "groupId": null,
    "TropiCards": [],
    "services": [
        {
            "slug": "CRYPTO_TOPUP",
            "enabled": true
        }
    ],
    "paymentMethods": [
        {
            "slug": "TPP",
            "name": "Tropipay",
            "enabled": true
        }
    ]
  }
]

Recuperar el saldo de una cuenta

Recupera el saldo de una cuenta específica.

GET/accounts/balance/{accountNumber}

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/balance/TP1234567890123456789012 \
  -H "Authorization: Bearer sk_test_..."

Respuesta

{
  "accountNumber": "TP00-0000-0000-0000-0000",
  "balance": 418090,
  "pendingIn": 1422276,
  "pendingOut": 0,
  "currency": "USDC"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
accountNumber	string	El número de cuenta único.
balance	integer	El saldo actual de la cuenta en céntimos.
pendingIn	integer	El monto de fondos entrantes pendientes de confirmación, en céntimos.
pendingOut	integer	El monto de fondos salientes pendientes de confirmación, en céntimos.
currency	string	El código de moneda de la cuenta (por ejemplo, USDC).

Recuperar todos los saldos de cuentas

Recupera la información de saldo de todas las cuentas del usuario.

GET/accounts/allBalance

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/allBalance \
  -H "Authorization: Bearer sk_test_..."

Respuesta

[
  {
    "balance": 418090,
    "currency": "USDC"
  },
  {
    "balance": 163202,
    "currency": "EUR"
  }
]

Parámetros de la respuesta

La respuesta es un array de objetos de cuenta, cada uno con los siguientes atributos:

Parámetro	Tipo	Descripción
balance	integer	El saldo total de la cuenta en céntimos.
currency	string	El código de moneda de la cuenta (por ejemplo, USDC, EUR).

Agregar cuenta Tropicard

Vincula una Tropicard a la cuenta del usuario.

POST/accounts/

curl -X POST https://sandbox.tropipay.me/api/v3/accounts/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tropicardNumber": "1234567890123456",
    "pin": "1234"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
tropicardNumber	string	Sí	Número de Tropicard de 16 dígitos
pin	string	Sí	Código PIN de 4 dígitos

Obtener dirección crypto para auto-recarga

Recupera una dirección de criptomoneda para depositar fondos en una cuenta.

GET/accounts/{accountId}/selfcharge/crypto

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/21221/selfcharge/crypto \
  -H "Authorization: Bearer sk_test_..."

Respuesta

{
  "feePercent": 300,
  "feeFixed": 0,
  "accounts": [
    {
      "address": "Bvmv25du1Um2gvMFAd3EQjUCano9a7tPXDp9KnxWRqjc",
      "network": "SOLANA",
      "currency": "USDC"
    }
  ]
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
feePercent	integer	La comisión de depósito como porcentaje (por ejemplo, 300 para 3.00%).
feeFixed	integer	Una comisión fija de depósito en céntimos.
accounts	array	Un array de direcciones de depósito disponibles.

Objeto Account dentro del array accounts

Parámetro	Tipo	Descripción
address	string	La dirección de la billetera de criptomoneda para el depósito.
network	string	La red blockchain (por ejemplo, SOLANA).
currency	string	El código de criptomoneda (por ejemplo, USDC).

Manejo de errores

La API de Cuentas utiliza códigos de respuesta HTTP convencionales para indicar el éxito o fracaso de una solicitud a la API.

Códigos de error comunes

Código	Descripción
400	Bad Request - Parámetros inválidos
401	Unauthorized - Autenticación inválida
403	Forbidden - Permisos insuficientes
404	Not Found - La cuenta no existe
409	Conflict - La cuenta ya existe o tiene un estado inválido
422	Unprocessable Entity - Datos de cuenta inválidos
429	Too Many Requests - Límite de tasa excedido
500	Internal Server Error

Ejemplo de respuesta de error

{
  "error": {
    "type": "invalid_request_error",
    "code": "account_not_found",
    "message": "No such account: acc_invalid",
    "param": "accountId"
  }
}