Usuarios

La API de Usuarios te permite gestionar perfiles de usuario, saldos, configuraciones de seguridad y preferencias de autenticación. Esto incluye operaciones como recuperar información del usuario, actualizar perfiles, gestionar la autenticación de dos factores y manejar códigos de seguridad.

El objeto User

{
  "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "state": 1,
  "kycLevel": 4,
  "balance": 163202,
  "pendingIn": 1339174,
  "pendingOut": 0,
  "twoFaMode": 1,
  "logo": "https://umedia.tropipay.com/develop/user-id/logo-257.png",
  "createdAt": "2022-06-10T11:48:38.319Z",
  "updatedAt": "2025-07-24T05:50:54.066Z"
}

Atributos

Atributo	Tipo	Descripción
id	string	Identificador único del usuario (UUID).
name	string	Nombre del usuario.
surname	string	Apellido del usuario.
email	string	Correo electrónico del usuario.
phone	string	Número de teléfono del usuario.
state	integer	Código numérico que representa el estado de la cuenta del usuario (por ejemplo, 1 para activa).
kycLevel	integer	Nivel de verificación Know Your Customer.
balance	integer	Saldo de la cuenta principal del usuario en céntimos.
pendingIn	integer	Monto total de fondos entrantes pendientes de confirmación, en céntimos.
pendingOut	integer	Monto total de fondos salientes pendientes de confirmación, en céntimos.
twoFaMode	integer	Código numérico del modo de autenticación de dos factores (por ejemplo, 1 para habilitado).
logo	string	URL del logo/avatar del perfil del usuario.
createdAt	string	Marca temporal de creación del usuario.
updatedAt	string	Marca temporal de la última actualización del perfil del usuario.

Recuperar perfil de usuario

Recupera los detalles del usuario autenticado.

GET/users/profile

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

Respuesta

{
  "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "state": 1,
  "kycLevel": 4,
  "balance": 163202,
  "pendingIn": 1339174,
  "pendingOut": 0,
  "twoFaMode": 1,
  "logo": "https://umedia.tropipay.com/develop/user-id/logo-257.png",
  "createdAt": "2022-06-10T11:48:38.319Z",
  "updatedAt": "2025-07-24T05:50:54.066Z",
  "group": { ... },
  "userDetail": { ... },
  "options": { ... }
}

Enviar código de seguridad

Este endpoint envía un código de seguridad al teléfono o correo electrónico del usuario. Es un paso crítico durante el proceso de registro para validar y actualizar la información de contacto del usuario, asegurando que la cuenta esté protegida.

POST/users/sendSecurityCode

curl -X POST https://sandbox.tropipay.me/api/v3/users/sendSecurityCode \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "callingCode": "+1",
    "phone": "234567890"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
type	string	Sí	Tipo de verificación (sms, email)
phone	string	Condicional	Requerido cuando el tipo es sms
callingCode	string	Condicional	Requerido cuando el tipo es sms. Prefijo telefónico del país del usuario.
email	string	Condicional	Requerido cuando el tipo es email

Validar token de seguridad

Valida un código de seguridad que fue enviado previamente al usuario.

POST/users/validateToken

curl -X POST https://sandbox.tropipay.me/api/v3/users/validateToken \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "securityCode": "123456",
    "type": "sms"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
securityCode	string	Sí	El código de seguridad de 6 dígitos
type	string	Sí	Tipo de verificación (sms, email, totp)

Respuesta

Una validación exitosa devuelve un booleano isValid, el objeto de usuario completo y un nuevo JSON Web Token (JWT) de corta duración. Este nuevo token debe usarse para acciones posteriores que requieran una sesión recientemente verificada.

info

Importante: Si el código de seguridad fue enviado a un nuevo número de teléfono no asociado previamente a la cuenta, una validación exitosa actualizará el perfil del usuario con el nuevo número.

{
  "isValid": true,
  "user": {
    "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
    "name": "John",
    "surname": "Doe",
    "email": "john.doe@example.com",
    "phone": "+3455555555",
    // ... other user fields
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Configurar autenticación de dos factores

Habilita o deshabilita la autenticación de dos factores para la cuenta de usuario.

POST/users/2fa

curl -X POST https://sandbox.tropipay.me/api/v3/users/2fa \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "type": "totp",
    "securityCode": "123456"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Si habilitar o deshabilitar el 2FA
type	string	Sí	Tipo de 2FA (totp, sms)
securityCode	string	Sí	Código de verificación

Obtener secreto 2FA

Genera un nuevo secreto TOTP para configurar la autenticación de dos factores.

POST/users/2fa/secret

curl -X POST https://sandbox.tropipay.me/api/v3/users/2fa/secret \
  -H "Authorization: Bearer sk_test_..."

Respuesta

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
secret	string	Secreto TOTP codificado en Base32
qrCodeUrl	string	Data URL del código QR para una configuración fácil

Cambiar contraseña

Cambia la contraseña de la cuenta de usuario.

POST/users/pass

curl -X POST https://sandbox.tropipay.me/api/v3/users/pass \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "oldPass": "password123",
    "newPass": "newpassword456"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
oldPass	string	Sí	Contraseña actual
newPass	string	Sí	Nueva contraseña

Deshabilitar cuenta de usuario

Deshabilita la cuenta de usuario, impidiendo el acceso futuro.

POST/users/disable

curl -X POST https://sandbox.tropipay.me/api/v3/users/disable \
  -H "Authorization: Bearer sk_test_..."

Respuesta

{
  "success": true,
  "message": "User account has been disabled"
}

Manejo de errores

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

• El rango 2xx indica éxito
• El rango 4xx indica un error producido por la información proporcionada
• El rango 5xx indica un error en los servidores de TropiPay

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 - El recurso no existe
429	Too Many Requests - Límite de tasa excedido
500	Internal Server Error