External API - Guia de Integracion

Que es la External API

La External API de Avirato Payments permite a integradores externos (ERPs, plataformas de e-commerce, sistemas de gestion, etc.) procesar pagos online y pagos POS de forma segura, sin necesidad de conocer la infraestructura interna del sistema.

Con una sola integracion puedes:

Crear sesiones de pago online y redirigir al cliente a una pagina de pago segura
Procesar pagos POS enviando un cobro directamente a un terminal fisico
Modificar pagos: reembolsos totales y parciales, capturas de preautorizacion, cancelaciones y extensiones de preautorizacion
Consultar pagos: obtener detalles de una sesion, listar sesiones con filtros y paginacion, listar modificaciones

Entornos: Live y Test

La External API ofrece dos entornos completamente independientes:

Live	Test
Proposito	Procesar pagos reales	Integrar y probar sin dinero real
URL base	`https://aviratopayments.com/external/v1/`	`https://aviratopayments.com/external/v1/test/`
API Keys	Keys de entorno Live	Keys de entorno Test
Pagos online	Procesador real	Simulacion con tarjetas ficticias
Pagos POS	Terminal fisico real	Simulacion inmediata (magic amounts)
Webhooks	Enviados por el procesador real	Generados automaticamente por el backend
Dinero real	Si	No

Recomendacion: Integra primero en el entorno Test para verificar que tu sistema funciona correctamente. Una vez validado, cambia a Live simplemente usando tu API key de produccion y eliminando /test/ de las URLs.

URL Base

Live: https://aviratopayments.com/external/v1/
Test: https://aviratopayments.com/external/v1/test/

Todos los endpoints de esta documentacion muestran la URL completa del entorno Live. Para usar el entorno Test, inserta /test/ despues de /v1/. Por ejemplo:

Live: POST https://aviratopayments.com/external/v1/payment/session
Test: POST https://aviratopayments.com/external/v1/test/payment/session

Autenticacion rapida

Todas las peticiones requieren una API key en la cabecera X-API-KEY:

X-API-KEY: tu_api_key_aqui

Las API keys se gestionan desde el dashboard de Avirato Payments (seccion Integraciones > API Keys). Cada key esta vinculada a un webcode (identificador de negocio) y un entorno (Live o Test).

Ademas, todas las peticiones POST aceptan opcionalmente la cabecera Idempotency-Key para evitar operaciones duplicadas. Recomendamos usarla siempre en produccion. Reutilizar la misma clave con un body distinto u otro endpoint devuelve 409 Conflict (ver Autenticacion y Manejo de errores).

Para mas detalle: Autenticacion

Estructura de respuestas

Respuesta exitosa

Todas las respuestas exitosas siguen esta estructura:

{
  "success": true,
  "data": { ... }
}

El contenido de data varia segun el endpoint. El campo success siempre es true en respuestas 2xx.

Respuesta con error

{
  "success": false,
  "error": {
    "message": "Descripcion del error en ingles",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123..."
  }
}

El traceId es unico por peticion. Incluyelo siempre cuando contactes con soporte tecnico. Ver Manejo de errores para el catalogo completo.

Conceptos clave antes de empezar

Sesion vs Pago (para pagos online)

Es fundamental entender esta distincion:

Sesion (sessionId): Es la intencion de cobro que tu sistema crea. Contiene el importe, URLs de retorno, etc.
Pago (paymentReference): Es la transaccion real autorizada por el procesador. Solo existe cuando el cliente completa el pago con exito.

Regla practica: Usa sessionId para consultar estado. Usa paymentReference para modificar (reembolsar, capturar, cancelar, extender).

Ver Pagos Online - Sesion vs Pago para la explicacion completa.

Operaciones asincronas

Las modificaciones (refund, capture, cancel, extend) son asincronas. La API acepta la peticion inmediatamente (HTTP 202) pero la operacion se procesa en background. El estado inicial es pending (refunds) o received (capture, cancel, extend) y evoluciona a success o failed conforme el procesador confirma.

Los pagos POS son sincronos: la peticion espera a que el terminal responda.

En entorno Test: Las modificaciones se resuelven de forma casi inmediata (el backend simula la respuesta del procesador). Recibiras el webhook de confirmacion en segundos.

Flujo tipico de integracion

1. Pago online

Tu sistema                        Avirato Payments                  Cliente
    |                                    |                              |
    |-- POST /payment/session ---------->|                              |
    |<-- 201 { sessionId, paymentUrl } --|                              |
    |                                    |                              |
    |-- Redirige al cliente ------------>+---------------------------->|
    |                                    |     (pagina de pago segura)  |
    |                                    |<-- Completa el pago ---------|
    |                                    |                              |
    |                                    |-- Redirige a urlOk -------->|
    |                                    |   (con datos cifrados)       |
    |                                    |                              |
    |-- GET /payment/session/{id} ------>|                              |
    |<-- { status: completed,            |                              |
    |      paymentReference: "..." } ----|                              |
    |                                    |                              |
    |   (Ahora puedes hacer refund,      |                              |
    |    capture, etc. con paymentRef)   |                              |

2. Pago POS

Tu sistema                        Avirato Payments         Terminal TPV
    |                                    |                      |
    |-- POST /pos/payment ------------->|                      |
    |                                    |-- Envia cobro ----->|
    |                                    |    (cliente paga     |
    |                                    |     en terminal)     |
    |                                    |<-- Resultado --------|
    |<-- 200 { status: success,          |                      |
    |          paymentReference } --------|                      |

Nota: Estos flujos funcionan de forma identica en el entorno Test, sustituyendo /external/v1/ por /external/v1/test/. La unica diferencia es que en Test el pago online se completa con tarjetas ficticias y el pago POS se simula con magic amounts (sin terminal real).

Diferencias clave entre Test y Live

Aspecto	Live	Test
Pago online	El cliente paga con tarjeta real en el formulario de pago	El cliente usa tarjetas ficticias en formulario simulado
Pago POS	El terminal fisico procesa el cobro	El resultado se simula inmediatamente segun el importe
Webhooks	Enviados por el procesador real cuando confirma la operacion	Generados automaticamente por el backend al completar la simulacion
Modificaciones	Procesadas por el procesador real (puede tardar segundos/minutos)	Simuladas instantaneamente por el backend
Referencias	Infijo `-EXT-`, `-PXT-`, `-POSX-`, `-RFX-`, `-CTX-`, etc.	Infijo `-EXTT-`, `-PXTT-`, `-POSXT-`, `-RFXT-`, `-CTXT-`, etc.
Dinero	Transacciones reales	Sin movimiento de dinero
Datos	Completamente aislados	Completamente aislados (no se mezclan con live)

Indice de endpoints

Pagos Online

Metodo	Endpoint	Descripcion	HTTP Status
POST	`/payment/session`	Crear sesion de pago	201
GET	`/payment/session/{sessionId}`	Obtener detalle de sesion	200
GET	`/payment/sessions`	Listar sesiones	200

Modificaciones (aplican a pagos online y POS)

Metodo	Endpoint	Descripcion	HTTP Status
POST	`/payment/refund`	Reembolsar pago	202
POST	`/payment/capture`	Capturar preautorizacion	202
POST	`/payment/cancel`	Cancelar preautorizacion	202
POST	`/payment/extend`	Extender preautorizacion	202
GET	`/payment/session/{sessionId}/modifications`	Listar modificaciones de una sesion	200
GET	`/pos/payment/{posPaymentId}/modifications`	Listar modificaciones de un pago POS	200
GET	`/modifications`	Listar todas las modificaciones	200

Pagos POS

Metodo	Endpoint	Descripcion	HTTP Status
GET	`/pos/terminals`	Listar terminales activos	200
POST	`/pos/payment`	Crear pago POS	200
GET	`/pos/payments`	Listar pagos POS	200

Recuerda: Para usar cualquier endpoint en el entorno Test, anade /test/ despues de /v1/. Ejemplo: POST /external/v1/test/payment/session.

Documentación para desarrolladores