Skip to main content

El API PayGate PoS es una solución integral de procesamiento de pagos diseñada específicamente para implementaciones de Punto de Venta (PoS). Este API proporciona un conjunto completo de endpoints para manejar diversas operaciones de pago, incluyendo pagos, devoluciones, pre-autorizaciones y gestión de terminales.

URL Base: https://terminal-ip:8081/api/v1

Autenticación​

La API utiliza autenticación mediante clave API para todas las solicitudes:

  • Header: X-API-Key
  • Descripción: Clave API para autorizar las solicitudes
  • Requerido: Sí. Será enviado por el punto de venta.

Adicionalmente, para operaciones específicas del terminal:

  • Header: X-Terminal-Serial
  • Descripción: Número de serie del terminal para autorización
  • Requerido: Para ciertas operaciones. Se calcula automáticamente.

Cabeceras Comunes​

Todas las solicitudes de la API requieren el siguiente header:

  • Idempotency-Key: Clave única para idempotencia (requerido)

Estructura Base de Solicitud​

Todas las solicitudes siguen una estructura base común:

{
  "object": "string",     // Tipo de operación (init, payments, refunds, preauths, etc.)
  "locale": "string",     // Idioma para las respuestas (es_ES, en_US)
  "print": false,         // Opcional: Imprimir resultado en terminal (por defecto: false)
  "metadata": {           // Opcional: Pares clave-valor personalizados
    "custom_field_1": "anyvalue",
    "custom_field_n": "anyvalue"
  }
}

Estructura Base de Respuesta​

Todas las respuestas incluyen campos comunes:

{
  "request_id": "string",  // Identificador único de transacción
  "object": "string",      // Tipo de operación
  "locale": "string"       // Idioma de respuesta
}

Gestión de Errores​

La API utiliza códigos de estado HTTP estándar:

  • 200: Éxito - Operación procesada correctamente
  • 400: Solicitud Incorrecta - Parámetros inválidos o campos requeridos faltantes
  • 401: No Autorizado - Clave API inválida
  • 402: Pago Fallido - Operación fallida o denegada
  • 403: Prohibido - La clave API carece de permisos requeridos
  • 404: No Encontrado - El recurso solicitado no existe
  • 500: Error Interno del Servidor - Error del sistema

Formato de Respuesta de Error​

{
  "error": {
    "code": "190",                         // Código de error específico
    "message": "denegada por motivos diversos" // Descripción del error
  }
}

Tipos de Datos​

Códigos de Moneda​

  • Formato: ISO 4217 en minúsculas (ej., eur, usd)
  • Patrón: ^[a-z]{3}$

IDs de Pedido​

  • Formato: Alfanumérico con guiones
  • Patrón: ^[a-zA-Z0-9-]{2,255}$
  • Longitud: 2-255 caracteres

BIN de Tarjeta​

  • Formato: Número de 6-8 dígitos
  • Patrón: ^[0-9]{6,8}
  • Ejemplo: 543200

Modos de Autorización​

  • D: ONLINE - Autorización en línea con el banco
  • O: OFFLINE - Autorización offline (cuando no hay conectividad)

Subtipos de Tarjeta​

  • corporate: Tarjeta corporativa
  • consumer: Tarjeta de consumo

Tipos de Token​

  • local: Token local (almacenado en el terminal)
  • scheme: Token del esquema (Visa, Mastercard, etc.)

Acciones de Token​

  • store: Tokenizar tarjeta (guardar para uso futuro)
  • pay: Pagar con token (usar token existente)

Formatos de Firma​

  • propietary: Formato propietario
  • bmp_type: Formato tipo BMP
  • jpg: Formato JPEG
  • tif: Formato TIFF
  • bmp: Formato BMP

Mejores Prácticas​

  1. Idempotencia: Siempre use headers Idempotency-Key únicos para prevenir transacciones duplicadas
  2. Manejo de Errores: Implemente manejo de errores apropiado para todos los códigos de respuesta
  3. Tokenización: Use tokens para pagos recurrentes para mejorar la seguridad
  4. Impresión: Configure print: true cuando desee impresión automática en el terminal
  5. Callbacks: Use URLs de callback para recibir información en tiempo real del PIN pad
  6. Metadatos: Use campos de metadatos para almacenar información personalizada sobre las transacciones
  7. Validación: Valide siempre los importes y monedas antes de enviar las solicitudes
  8. Logging: Mantenga logs detallados de todas las transacciones para auditoría

Consideraciones de Seguridad​

  1. Seguridad de Clave API: Mantenga las claves API seguras y rótelas regularmente
  2. HTTPS: Siempre use HTTPS para todas las comunicaciones de la API
  3. Cumplimiento PCI: Siga las directrices PCI DSS al manejar datos de tarjetas
  4. Almacenamiento de Tokens: Almacene tokens de forma segura y respete las fechas de expiración
  5. Logging de Auditoría: Mantenga logs de todas las interacciones de la API para cumplimiento
  6. Validación de Entrada: Valide siempre los datos de entrada antes de procesarlos
  7. Manejo de Errores: No exponga información sensible en los mensajes de error