Saltar al contenido principal

Integración API

La API PayGate PoS es una solución integral de procesamiento de pagos diseñada específicamente para implementaciones de Punto de Venta (PoS). Esta API proporciona un conjunto completo de endpoints para manejar diversas operaciones de pago, incluyendo pagos, reembolsos, 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
}

Endpoints API​

1. Inicialización del Dispositivo​

POST /init​

Inicializa el dispositivo de pago y recupera información del terminal. Esta operación es fundamental para establecer la comunicación con el terminal y obtener información sobre sus capacidades y configuración.

Cuerpo de la Solicitud:

{
  "object": "init",
  "locale": "es_ES",
  "datetime": "2020-01-01T00:00:00Z",  // Opcional: Formato ISO 8601
  "callback_url": "https://example.com/callback"  // Opcional: URL para mostrar información
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "init",
  "locale": "es_ES",
  "serial_number": "58233707725",        // Número de serie del terminal
  "buffer_size": "00009990",             // Tamaño del buffer disponible
  "public_keys_version": "000",          // Versión de claves públicas
  "symmetric_keys_version": "223",       // Versión de claves simétricas
  "param_version": "000",                // Versión de parámetros
  "terminal_vendor": "28",               // Código del fabricante del terminal
  "terminal_model": "A8",                // Modelo del terminal
  "capabilities": "FD02",                // Capacidades del terminal
  "app_name": "APPPUP01",                // Nombre de la aplicación
  "app_version": "1907",                 // Versión de la aplicación
  "spec_version": "191",                 // Versión de especificación
  "initialized_boxes": "02",             // Cajas inicializadas
  "boxes": {                             // Información de los cajones de claves de PIN
    "02": "223A84EA459DC39",
    "03": "001936DDF8BDA45"
  },
  "pci_scenary": "1"                     // Escenario de cumplimiento PCI
}

2. Operaciones de Pago​

POST /payments​

Procesa una transacción de pago con un importe especificado. Esta es la operación principal para realizar cobros con tarjeta de crédito/débito.

Cuerpo de la Solicitud:

{
  "object": "payments",
  "locale": "es_ES",
  "amount": 1000,                        // importe en céntimos (10.00 EUR)
  "currency": "eur",                     // Código de moneda (ISO 4217)
  "order": "ORDER-00001",                // Identificador único del pedido
  "token": {                             // Opcional: Gestión de tokens
    "id": "token-1234",                  // ID del token
    "expires_at": "2020-01-01T00:00:00Z", // Fecha de expiración
    "type": "local",                     // Tipo de token (local/scheme)
    "action": "store"                    // Acción (store para guardar, pay para pagar)
  },
  "order_summary": {                     // Opcional: Resumen del ticket de venta
    "total": 1000,                       // Total final
    "discount": 0,                       // Descuentos aplicados
    "shipping": 0,                       // Gastos de envío
    "subtotal": 1000,                    // Subtotal
    "tip": 0                             // Propina
  },
  "order_details": [                     // Opcional: Detalles de los artículos
    {
      "product": "SKU000001",            // SKU del producto
      "quantity": 1,                     // Cantidad
      "amount": 100,                     // Precio unitario
      "tax": 9,                          // Impuestos
      "discount": 0,                     // Descuento del artículo
      "total": 109                       // Total del artículo
    }
  ],
  "callback_url": "https://example.com/callback"  // URL para notificaciones
}

Respuesta (200) - Éxito:

{
  "request_id": "unique-id",
  "object": "payments",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "token": {                             // Presente si se solicitó tokenización
    "id": "token-1234",
    "expires_at": "2020-01-01T00:00:00Z",
    "type": "local"
  },
  "payment_details": {
    "card_authorization_code": "123456",  // Código de autorización
    "card_processor_center": "REDSYS",    // Centro procesador
    "card_bin": "543200",                 // BIN de la tarjeta (primeros 6 dígitos)
    "card_masked": "543200*****1234",     // Tarjeta enmascarada
    "card_subtype": "corporate",          // Subtipo (corporate/consumer)
    "card_brand": "VISA",                 // Marca de la tarjeta
    "card_type": "credit",                // Tipo (credit/debit)
    "card_issuer": "Caixabank",           // Emisor de la tarjeta
    "card_issuer_code": 2100,             // Código del emisor
    "card_authorization_mode": "D"        // Modo de autorización (D=Online, O=Offline)
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data", // Datos codificados para impresión
    "printable_data": {                   // Datos estructurados para impresión
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

Respuesta (402) - Pago Denegado:

{
  "request_id": "unique-id",
  "object": "payments",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "payment_details": {
    "card_declined_code": "190",          // Código de denegación
    "card_declined_message": "DENEGADA POR MOTIVOS DIVERSOS", // Mensaje de denegación
    "card_processor_center": "REDSYS",
    "card_bin": "543200",
    "card_masked": "543200*****1234",
    "card_subtype": "corporate",
    "card_brand": "VISA",
    "card_type": "credit",
    "card_issuer": "Caixabank",
    "card_issuer_code": 2100
  },
  "error": {
    "code": "190",
    "message": "denegada por motivos diversos"
  }
}

DELETE /payments/{request_id}​

Cancela una operación de pago. Útil para cancelar transacciones que están en proceso.

Cuerpo de la Solicitud:

{
  "object": "payments/cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur"
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card"
}

3. Operaciones de Reembolso​

POST /refunds​

Procesa una transacción de reembolso referenciada a un pedido existente. Permite devolver total o parcialmente el importe de una transacción anterior.

Cuerpo de la Solicitud:

{
  "object": "refunds",
  "locale": "es_ES",
  "amount": 1000,                        // importe a reembolsar
  "currency": "eur",
  "order": "ORDER-00001",                // ID del pedido original
  "token": {                             // Opcional: Gestión de tokens
    "id": "token-1234",
    "expires_at": "2020-01-01T00:00:00Z",
    "type": "local",
    "action": "store"
  },
  "order_summary": {                     // Opcional: Resumen del ticket de reembolso
    "total": 1000,
    "discount": 0,
    "shipping": 0,
    "subtotal": 1000,
    "tip": 0
  },
  "order_details": [                     // Opcional: Artículos a reembolsar
    {
      "product": "SKU000001",
      "quantity": 1,
      "amount": 100,
      "tax": 9,
      "discount": 0,
      "total": 109
    }
  ]
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "refunds",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "token": {                             // Presente si se solicitó tokenización
    "id": "token-1234",
    "expires_at": "2020-01-01T00:00:00Z",
    "type": "local"
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data",
    "printable_data": {
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

DELETE /refunds/{request_id}​

Cancela una operación de reembolso.

Cuerpo de la Solicitud:

{
  "object": "payments/cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur"
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card"
}

4. Operaciones de Pre-autorización​

POST /preauths​

Procesa una transacción de pre-autorización. Útil para reservar fondos sin completar la transacción inmediatamente (hoteles, alquiler de coches, etc.).

Cuerpo de la Solicitud:

{
  "object": "preauths",
  "locale": "es_ES",
  "amount": 1000,                        // importe a pre-autorizar
  "currency": "eur",
  "order": "ORDER-00001",
  "order_summary": {                     // Opcional: Resumen del ticket de venta
    "total": 1000,
    "discount": 0,
    "shipping": 0,
    "subtotal": 1000,
    "tip": 0
  },
  "order_details": [                     // Opcional: Detalles de los artículos
    {
      "product": "SKU000001",
      "quantity": 1,
      "amount": 100,
      "tax": 9,
      "discount": 0,
      "total": 109
    }
  ]
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "preauths",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "payment_details": {
    "card_authorization_code": "123456",  // Código de autorización (necesario para confirmar)
    "card_processor_center": "REDSYS",
    "card_bin": "543200",
    "card_masked": "543200*****1234",
    "card_subtype": "corporate",
    "card_brand": "VISA",
    "card_type": "credit",
    "card_issuer": "Caixabank",
    "card_issuer_code": 2100
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data",
    "printable_data": {
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

DELETE /preauth/{request_id}​

Cancela una pre-autorización (libera/desbloquea los fondos reservados).

Cuerpo de la Solicitud:

{
  "object": "preauths/cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "payment_details": {
    "card_authorization_code": "123456"   // Código de la pre-autorización original
  }
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "preauths/cancel",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card"
}

POST /preauth/{request_id}/confirm​

Confirma una pre-autorización (cobra los fondos previamente reservados).

Cuerpo de la Solicitud:

{
  "object": "preauths/confirm",
  "locale": "es_ES",
  "amount": 1000,                        // importe a confirmar (puede ser menor al pre-autorizado)
  "currency": "eur",
  "order": "ORDER-00001",
  "payment_method": "card",
  "payment_details": {
    "card_authorization_code": "123456"   // Código de la pre-autorización original
  }
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "payments",                  // Cambia a "payments" al confirmar
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "payment_details": {
    "card_authorization_code": "123456",
    "card_processor_center": "REDSYS",
    "card_bin": "543200",
    "card_masked": "543200*****1234",
    "card_subtype": "corporate",
    "card_brand": "VISA",
    "card_type": "credit",
    "card_issuer": "Caixabank",
    "card_issuer_code": 2100,
    "card_authorization_mode": "D"
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data",
    "printable_data": {
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

5. Totales de Ticket​

GET /totals​

Recupera los totales del ticket. Útil para cierres de caja y reportes de ventas.

Parámetros de Consulta:

  • session (requerido): Tipo de sesión
    • current: Cierra la sesión actual y devuelve totales
    • last: Devuelve totales de la última sesión
    • last1: Devuelve totales de la penúltima sesión

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "totals",
  "locale": "es_ES",
  "totals": {
    "currency": "eur",                   // Moneda de los totales
    "total": 1000,                       // Total general
    "count": {                           // Conteo de transacciones
      "refunds": 100,                    // Número de reembolsos
      "payments": 100,                   // Número de pagos
      "payments_cancelled": 100,         // Número de pagos cancelados
      "refunds_cancelled": 100           // Número de reembolsos cancelados
    },
    "sum": {                             // Suma de importes
      "refunds": 100,                    // Total de reembolsos
      "payments": 100,                   // Total de pagos
      "payments_cancelled": 100,         // Total de pagos cancelados
      "refunds_cancelled": 100           // Total de reembolsos cancelados
    },
    "card_types": {                      // Desglose por tipo de tarjeta
      "mastercard": {
        "total": 100,                    // Total para Mastercard
        "count": {                       // Conteo por Mastercard
          "refunds": 100,
          "payments": 100,
          "payments_cancelled": 100,
          "refunds_cancelled": 100
        },
        "sum": {                         // Suma por Mastercard
          "refunds": 100,
          "payments": 100,
          "payments_cancelled": 100,
          "refunds_cancelled": 100
        }
      }
    }
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data",
    "printable_data": {
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

6. Gestión de Configuración​

POST /tools/config​

Actualiza la configuración de PayGate o archivos BIN. Permite recargar configuraciones sin reiniciar el terminal.

Parámetros de Consulta:

  • action (requerido): Tipo de acción
    • reload: Recarga la configuración
    • reloadbinlist: Recarga la lista de BIN

Cuerpo de la Solicitud:

{
  "object": "config/reload",
  "locale": "es_ES"
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "config/reload",
  "locale": "es_ES",
  "digest": "075bcb53e75c2400cb0c25ae5c7c77538f6a7a61bf17bd1b95ab3ef84e7bd603" // Hash de verificación
}

7. Gestión del Terminal​

POST /tools/idle​

Establece el PIN pad en modo inactivo. Útil para ahorrar energía o cuando no se necesita el terminal.

Cuerpo de la Solicitud:

{
  "object": "idle",
  "locale": "es_ES"
}

Respuesta (200):

{
  "object": "idle"
}

POST /tools/file3000​

Carga el archivo 3000. Este archivo contiene configuraciones específicas del terminal.

Parámetros de Consulta:

  • action (requerido): load

Cuerpo de la Solicitud:

{
  "object": "file3000/load",
  "locale": "es_ES",
  "path": "/storage/emulated/0/Android/data/com.sipay.paygate/files/3000.file" // Ruta del archivo
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "load3000",
  "locale": "es_ES",
  "digest": "075bcb53e75c2400cb0c25ae5c7c77538f6a7a61bf17bd1b95ab3ef84e7bd603"
}

POST /tools/pinonline_keys​

Actualiza las claves PIN online. Necesario para mantener la seguridad del terminal.

Parámetros de Consulta:

  • action (requerido): update

Cuerpo de la Solicitud:

{
  "object": "pinonline_keys/update",
  "locale": "es_ES",
  "box": "2"                             // Número de caja de seguridad
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "update_pinonline_keys",
  "locale": "es_ES"
}

8. Información del Sistema​

GET /version​

Obtiene información de la versión de la API. Útil para verificar compatibilidad.

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "version",
  "locale": "es_ES",
  "paygate": "1.0.0",                    // Versión de PayGate
  "pup": "1.9"                           // Versión del PUP (Payment Unit Protocol)
}

GET /health​

Verifica el estado de salud del centro de procesamiento de datos. Útil para monitoreo.

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "keepalive",
  "locale": "es_ES",
  "result": [
    {
      "datacenter": "node1.pcp.sipay.es", // Nombre del datacenter
      "response_time": 240.4,             // Tiempo de respuesta en ms
      "status": "success"                 // Estado de la conexión
    },
    {
      "datacenter": "node2.pcp.sipay.es",
      "response_time": 50.11,
      "status": "success"
    }
  ]
}

9. Detalles de Operación​

GET /operations​

Obtiene datos de una operación (llamada REQUEST PRINTABLE DATA al gateway). Útil para recuperar información detallada de transacciones anteriores.

Parámetros de Consulta:

  • request_id: Identificador de la transacción

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "operations",
  "locale": "es_ES",
  "order": "ORDER-00001",
  "amount": 1000,
  "currency": "eur",
  "payment_method": "card",
  "payment_details": {
    "card_authorization_code": "123456",
    "card_processor_center": "REDSYS",
    "card_bin": "543200",
    "card_masked": "543200*****1234",
    "card_subtype": "corporate",
    "card_brand": "VISA",
    "card_type": "credit",
    "card_issuer": "Caixabank",
    "card_issuer_code": 2100,
    "card_authorization_mode": "D"
  },
  "printing_details": {
    "printable_data_encoded": "base64-encoded-data",
    "printable_data": {
      "elemento_1": "value1",
      "elemento_n": "valueN"
    }
  }
}

10. Generación de Firma​

GET /tools/signature​

Genera una firma de documento. Útil para verificar la autenticidad de los datos.

Parámetros de Consulta:

  • action (requerido): sign

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "signature",
  "locale": "es_ES",
  "format": "propietary",                 // Formato de la firma
  "signature": "FFD8FFE000104A46494600010100000100010000FFDB004300FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDB004301FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC000110800C4012803012200021101031101FFC40017000101010100000000000000000000000000020103FFC4002710010100010303040105010000000000000001021121311241516171A1B13252628191D172FFC40014010100000000000000000000000000000000FFC40014110100000000000000000000000000000000FFDA000C03010002110311003F00E80000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000CB64E41A9B976C77BF0CDF2F49F355249C0340000000000000000000000000000000000000000000000001372ED8EF7CF6805CB4DA6F7C131EF77BF44C74F5BDEA80000000000000000000000000000000000000000000000000046F971B63F605B72DA71DEFF8A924E1B269B40000000000000000000000000000000000000000000000000065BA6F5B6E9BD449D575BC76806F973B63E3CAC00000000000000000000000000000000000000000038004DCF1F7F646595BDAC9F60AB96FA63BD5B9E3329C49FCB75CBF4FC82CE11D5E71B19AF55DF89DBC837F2BADE3B4F2B000000000000000000000000000000000000000000002F1E5CB4CB2BBCFEF88EA0266327AD67E597A4F9ADCAE93D6ED1B2693406823F3FF009FB03F2BFB67CAAe32F66808E9B38CAFF3B9AE5399AFAC5809994BDF4F7532C97989E9F16CFA0588D729DA5F66F5CEFACF70506B2F00000000000000000000000000000000000000239CBD31FB5F0E78D926B79B6ECDD2E5CED3C7FA06F97A63F6B000000000000004F44F6F666994E2EBEEB011D5A732CFA54B2F15A9B8CBD81423A6CE32FECD729CCD7D81627AE77D67BB65978A0D00000000000000000000000000193192EBA3400000000000000000000000000D3564926F23400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007FFD9" // Firma codificada en base64
}

11. Modo Offline​

POST /offline​

Establece el sistema de pago en modo offline. Útil cuando no hay conectividad de red.

Parámetros de Consulta:

  • action (requerido): Tipo de acción
    • enable: Habilita el modo offline
    • disable: Deshabilita el modo offline
    • status: Verifica el estado del modo offline

Cuerpo de la Solicitud:

{
  "object": "offline",
  "locale": "es_ES"
}

Respuesta (200):

{
  "request_id": "unique-id",
  "object": "offline",
  "locale": "es_ES",
  "status": true                           // true = offline habilitado, false = online
}

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

Inicio rápido​

Pago Simple​

POST /payments
{
  "object": "payments",
  "locale": "es_ES",
  "amount": 2500,        // 25.00 EUR
  "currency": "eur",
  "order": "ORDER-001"
}

Pago con Tokenización​

POST /payments
{
  "object": "payments",
  "locale": "es_ES",
  "amount": 1500,
  "currency": "eur",
  "order": "ORDER-002",
  "token": {
    "action": "store"
  }
}

Pre-autorización para Hotel​

POST /preauths
{
  "object": "preauths",
  "locale": "es_ES",
  "amount": 5000,        // 50.00 EUR para depósito
  "currency": "eur",
  "order": "HOTEL-001"
}

Confirmación de Pre-autorización​

POST /preauth/HOTEL-001/confirm
{
  "object": "preauths/confirm",
  "locale": "es_ES",
  "amount": 3500,        // 35.00 EUR (importe final)
  "currency": "eur",
  "order": "HOTEL-001",
  "payment_details": {
    "card_authorization_code": "123456"
  }
}

Reembolso Parcial​

POST /refunds
{
  "object": "refunds",
  "locale": "es_ES",
  "amount": 500,         // 5.00 EUR de reembolso
  "currency": "eur",
  "order": "ORDER-001"
}