Especificaciones Técnicas

Documentación técnica completa para implementar el estándar de pago universal payware. Construido sobre estándares abiertos, diseñado para desarrolladores.

Especificaciones de Protocolo API

La API de payware está construida sobre principios modernos RESTful con estándares abiertos para interoperabilidad global.

Arquitectura API RESTful

Protocolo

  • Transporte: HTTPS/TLS 1.3
  • Autenticación: Basada en firma con identificador de socio
  • Formato: JSON (application/json, UTF-8)
  • Versionado: Basado en encabezado (Api-Version: 1)
  • Codificación: UTF-8

Métodos HTTP

  • POST: Crear transacción, procesar transacción
  • GET: Consultar estado e historial de transacciones
  • PATCH: Cancelar transacción
  • Marcas de tiempo: Formato timestamp UNIX
  • Moneda: Códigos de 3 letras ISO, formato decimal

Ejemplo de Solicitud

POST /api/transactions
Api-Version: 1
Content-Type: application/json

{
  "account": "GB29NWBK60161331926810",
  "friendlyName": "Your Favorite Shop",
  "callbackUrl": "https://merchant.com/callback",
  "trData": {
    "amount": "150.00",
    "currency": "GBP",
    "reasonL1": "Payment"
  },
  "trOptions": {
    "type": "QR",
    "timeToLive": 120
  }
}

Sistema de Callbacks

Notificaciones de estado de transacción en tiempo real mediante POST HTTPS a tu URL de callback.

Tipos de Callback

  • • TRANSACTION_FINALIZED

Estado de Transacción

  • • CONFIRMED - Pago exitoso
  • • DECLINED - Pago rechazado por el usuario
  • • FAILED - Error de procesamiento de pago
  • • CANCELLED - Transacción cancelada

Garantías de Entrega

  • • 15 intentos de reintento (una vez por segundo)
  • • Requiere respuesta con estado HTTP 200
  • • URLs de callback solo HTTPS
  • • Soporte de idempotencia mediante passbackParams

Seguridad y Criptografía

Estándares de Encriptación

Capa de Transporte

TLS 1.3 con secreto perfecto hacia adelante, intercambio de claves ECDHE

Datos en Reposo

Encriptación AES-256-GCM para datos sensibles almacenados

Firma de Mensajes

Firmas digitales HMAC-SHA256 y RSA-2048

Tokenización de Cuentas

La información sensible de cuentas nunca se transmite. En su lugar, los tokens representan el pago con alcance y vida útil limitados.

Vida útil: Multi-uso o limitado por tiempo (2 minutos por defecto)

Alcance: Específico del socio, limitado por monto

Detalles Técnicos de Métodos de Pago

Método Tecnología Formato de Datos Rango/Especificaciones
Código QR Escaneo de código de barras 2D Datos de transacción codificados Hasta 2KB de carga útil, corrección de errores
Código de barras Escaneo óptico 1D/2D Datos numéricos/alfanuméricos Code 128, dimensiones configurables
NFC Transmisión sin contacto Datos de transacción mediante toque NFC Proximidad 0-10cm, compatible ISO 14443
BLE Proximidad Bluetooth Datos de transacción mediante Bluetooth Rango 0-50m, soporte Bluetooth 5.0+
Soundbite Firma de audio audible para humanos Disparadores de sonido registrados Cualquier sonido audible (música, jingles, efectos)
Enlace Enlace profundo HTTPS URL con parámetros de pago URLs HTTPS seguras, codificación segura para URL
Texto Entrada de código alfanumérico Código de pago de 10 caracteres Cualquier medio: SMS, mensajería, email, papel

Requisitos de Integración

Requisitos Mínimos

  • Soporte HTTPS/TLS para comunicación segura
  • Encabezado Api-Version en todas las solicitudes API (Api-Version: 1)
  • URL de callback HTTPS para recibir actualizaciones de transacciones
  • Análisis de mensajes JSON (codificación UTF-8)
  • Identificador de socio y firma para autenticación API

Mejores Prácticas Recomendadas

  • Usa sandbox.payware.eu para integración y pruebas
  • Retorna HTTP 200 para reconocimiento de callback
  • Consulta estado de transacción mediante GET /transactions-history si falla el callback
  • Establece timeToLive apropiado para tu caso de uso (60-600 segundos)
  • Usa passbackParams para idempotencia y seguimiento de pedidos

SDKs y Librerías Oficiales

Librerías preconstruidas para integración rápida en lenguajes de programación populares.

JavaScript / Node.js

npm install @payware/sdk

  • • Soporte TypeScript
  • • Asincronía basada en promesas
  • • Compatible con React Native

Python

pip install payware

  • • Soporte Async/await
  • • Integración Django
  • • Type hints incluidos

Java

Dependencia Maven/Gradle

  • • Spring Boot starter
  • • Streams reactivos
  • • Soporte Android

PHP

composer require payware/php

  • • Compatible PSR-7/18
  • • Paquete Laravel
  • • Plugin WordPress

Ruby

gem install payware

  • • Integración Rails
  • • Helpers de prueba RSpec
  • • Soporte ActiveRecord

Go

go get payware.io/sdk

  • • Consciente del contexto
  • • Cero dependencias
  • • Seguro para concurrencia

Versionado y Ciclo de Vida de API

Estrategia de Versionado

La versión de API se especifica mediante el encabezado HTTP Api-Version. Las actualizaciones menores/de parche son retrocompatibles.

Actual: Api-Version: 1 (estable)

Método: Versionado basado en encabezado

Soporte: Mínimo 24 meses

Aviso: 12 meses antes de depreciación

Acceso a Registro de Cambios

Todos los cambios de API están documentados con guías de migración y código de ejemplo.

  • Feed de registro de cambios en tiempo real
  • Notificaciones por email
  • Herramientas de migración

¿Listo para Comenzar a Construir?

Accede a documentación completa de API, ejemplos de código y herramientas para desarrolladores

Ver Documentos para Desarrolladores Contactar Equipo Técnico