Índice de la documentación

API de Avirato Payments: guía de integración

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
  • Pagos recurrentes: cobrar periodicamente con la tarjeta guardada del cliente y gestionar su ciclo de vida (pausar, reactivar, cambiar tarjeta, cancelar)

Entornos: Live y Test

La External API ofrece dos entornos completamente independientes:

LiveTest
PropositoProcesar pagos realesIntegrar y probar sin dinero real
URL basehttps://aviratopayments.com/external/v1/https://aviratopayments.com/external/v1/test/
API keysKeys de entorno LiveKeys de entorno Test
Pagos onlineProcesador realSimulacion con tarjetas ficticias
Pagos POSTerminal fisico realSimulacion inmediata (magic amounts)
Pagos recurrentesCobros reales en su fechaCobros simulados (en su fecha o con simuladores)
WebhooksEnviados por el procesador realGenerados automaticamente por el backend
Dinero realSiNo

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:

bash
X-API-KEY: tu_api_key_aqui

Las API keys se gestionan desde el dashboard de Avirato Payments (seccion Integraciones > Configuracion > 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:

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

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

Respuesta con error

json
{
  "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 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

ClienteAvirato PaymentsTu sistemaAhora puedes hacer refund, capture, etc.POST /payment/session201 { sessionId, paymentUrl }Redirige a paymentUrlCompleta el pago (pagina segura)Redirige a urlOk (datos cifrados)GET /payment/session/{id}{ status: completed, paymentReference }

2. Pago POS

Terminal TPVAvirato PaymentsTu sistemaCliente paga en terminalPOST /pos/paymentEnvia cobroResultado200 { status: success, paymentReference }

3. Pago recurrente

ClienteAvirato PaymentsTu sistemaCada periodo cobra con la tarjeta guardadaPOST /subscriptions201 { linkId, paymentUrl }Redirige a paymentUrlPaga el primer importeWebhook SUBSCRIPTION_CREATED { subscriptionId }Webhook SUBSCRIPTION_RENEWED

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

AspectoLiveTest
Pago onlineEl cliente paga con tarjeta real en el formulario de pagoEl cliente usa tarjetas ficticias en formulario simulado
Pago POSEl terminal fisico procesa el cobroEl resultado se simula inmediatamente segun el importe
Pago recurrentePrimer pago en pagina segura real y cobros periodicos realesPagina simulada (el titular decide el resultado) y simuladores de renovacion y fin. No aparece en el panel
WebhooksEnviados por el procesador real cuando confirma la operacionGenerados automaticamente por el backend al completar la simulacion
ModificacionesProcesadas por el procesador real (puede tardar segundos/minutos)Simuladas instantaneamente por el backend
ReferenciasInfijo -EXT-, -PXT-, -POSX-, -RFX-, -CTX-, etc. Pagos recurrentes (igual en ambos entornos): -SB- (id), -LK- (link), -PYS- (pago inicial), -PYSS- (cobros periodicos)Infijo -EXTT-, -PXTT-, -POSXT-, -RFXT-, -CTXT-, etc. Pagos recurrentes: mismos infijos que Live (se distinguen por la key y la ruta /test/)
DineroTransacciones realesSin movimiento de dinero
DatosCompletamente aisladosCompletamente aislados (no se mezclan con live)

Indice de endpoints

Pagos online

MetodoEndpointDescripcionHTTP Status
POST/payment/sessionCrear sesion de pago201
GET/payment/session/{sessionId}Obtener detalle de sesion200
GET/payment/sessionsListar sesiones200

Modificaciones (aplican a pagos online y POS)

MetodoEndpointDescripcionHTTP Status
POST/payment/refundReembolsar pago202
POST/payment/captureCapturar preautorizacion202
POST/payment/cancelCancelar preautorizacion202
POST/payment/extendExtender preautorizacion202
GET/payment/session/{sessionId}/modificationsListar modificaciones de una sesion200
GET/pos/payment/{posPaymentId}/modificationsListar modificaciones de un pago POS200
GET/modificationsListar todas las modificaciones200

Pagos POS

MetodoEndpointDescripcionHTTP Status
GET/pos/terminalsListar terminales activos200
POST/pos/paymentCrear pago POS200
GET/pos/paymentsListar pagos POS200

Pagos recurrentes

MetodoEndpointDescripcionHTTP Status
POST/subscriptionsCrear pago recurrente (link de pago)201
GET/subscriptionsListar pagos recurrentes200
GET/subscriptions/{id}Detalle200
GET/subscriptions/{id}/paymentsHistorial de pagos200
GET/subscriptions/{id}/chargesCola de cobros200
PATCH/subscriptions/{id}Modificar200
POST/subscriptions/{id}/pausePausar200
POST/subscriptions/{id}/reactivateReactivar200
POST/subscriptions/{id}/update-cardLink para nueva tarjeta200
POST/subscriptions/{id}/cancelCancelar200
GET/subscriptions/linksListar links200
GET/subscriptions/links/{linkId}Detalle de link200
POST/subscriptions/links/{linkId}/cancelCancelar link200

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

Siguiente paso

  1. Configura tu autenticacion
  2. Crea tu primer pago online
  3. O empieza con pagos POS
  4. Aprende a modificar pagos
  5. Consulta pagos y modificaciones
  6. Cobra pagos recurrentes
  7. Recibe notificaciones via webhooks
  8. Manejo de errores
  9. Ejemplos completos end-to-end
Demander une démo