Saltar al contenido principal

Autenticación

La API de TropiPay distingue entre dos contextos principales de autenticación dependiendo de la acción a realizar:

  1. Autenticación a nivel de aplicación (Servidor-a-Servidor): Se utiliza para operaciones que tu aplicación realiza por su propia cuenta. Este es el método más común y usa una clave de API y un secreto para obtener un token de portador. Este flujo es ideal para procesos automatizados que se ejecutan en tu backend.

  2. Autenticación a nivel de usuario: Requerida para acciones que necesitan el consentimiento explícito de un usuario, como operaciones que involucran su saldo personal o confirmaciones biométricas. Este flujo generalmente implica redirigir al usuario a TropiPay para autorizar la acción.

Este documento se centra principalmente en la Autenticación a nivel de aplicación.

TropiPay usa claves de API para autenticar las solicitudes servidor-a-servidor. Puedes ver y gestionar tus claves de API en el Dashboard de TropiPay.

Tus claves de API otorgan muchos privilegios, así que asegúrate de mantenerlas seguras. No compartas tus claves secretas de API en áreas accesibles públicamente como GitHub, código del lado del cliente, etc.

La autenticación con la API se realiza mediante HTTP Bearer Authentication. Proporciona tu clave de API como el valor del token de portador.

Todas las solicitudes a la API deben realizarse mediante HTTPS. Las llamadas por HTTP simple fallarán. Las solicitudes a la API sin autenticación también fallarán.

URL base​

https://sandbox.tropipay.me/api/v3

Formato de la solicitud​

  • Todos los endpoints aceptan y devuelven datos en formato JSON
  • Las fechas están en formato ISO 8601 (UTC)
  • Los montos están en céntimos (100 = $1.00)
  • Content-Type: application/json

Encabezados requeridos​

Content-Type: application/json
Authorization: Bearer <access_token>
X-Device-Id: <device_id>  // Opcional, requerido para operaciones biométricas

Obtener token de acceso​

Para autenticarte con la API de TropiPay, primero necesitas obtener un token de acceso usando las credenciales de tu aplicación.

Solicitud​

POST/access/token
curl -X POST https://sandbox.tropipay.me/api/v3/access/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

Parámetros​

ParámetroTipoRequeridoDescripción
client_idstringSíEl client ID de tu aplicación
client_secretstringSíEl client secret de tu aplicación
grant_typestringSíDebe ser client_credentials

Respuesta​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJ5b3VyX2NsaWVudF9pZCIsImlhdCI6MTYzOTc0NDgwMCwiZXhwIjoxNjM5ODMxMjAwfQ.example_signature",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read write"
}

Parámetros de la respuesta​

ParámetroTipoDescripción
access_tokenstringEl token de acceso a usar en las solicitudes a la API
token_typestringSiempre "Bearer"
expires_inintegerTiempo de expiración del token en segundos
scopestringPermisos concedidos

Usar el token de acceso​

Incluye el token de acceso en el encabezado Authorization de todas las solicitudes a la API:

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

Respuestas de error​

Si la autenticación falla, recibirás una respuesta 401 Unauthorized:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "Invalid client credentials"
  }
}

Mejores prácticas de seguridad​

  • Mantén tus claves de API seguras y nunca las expongas en código del lado del cliente
  • Usa HTTPS para todas las solicitudes a la API
  • Rota tus claves de API regularmente
  • Monitorea el uso de tu API en busca de actividad inusual
  • Almacena las credenciales de forma segura usando variables de entorno o almacenes seguros

Límite de tasa​

Las solicitudes a la API están sujetas a limitación de tasa. Si excedes el límite, recibirás una respuesta 429 Too Many Requests. La respuesta incluirá headers que indican tu estado actual de límite de tasa:

  • X-RateLimit-Limit: El número máximo de solicitudes permitidas por ventana de tiempo
  • X-RateLimit-Remaining: El número de solicitudes restantes en la ventana de tiempo actual
  • X-RateLimit-Reset: El momento en que se reinicia el límite de tasa (timestamp Unix)