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
• 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:

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 > 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:

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

2. Pago POS

3. Pago recurrente

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

Indice de endpoints

Pagos online

Modificaciones (aplican a pagos online y POS)

Pagos POS

Pagos recurrentes

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

Autenticacion

API keys

Todas las peticiones a la External API requieren una API key valida en la cabecera HTTP X-API-KEY.

Cabeceras requeridas

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Entornos

La External API dispone de dos entornos independientes: Live y Test. Cada entorno tiene sus propias API keys, su propio client secret y sus propios datos (completamente aislados entre si).

API keys de Live

Las API keys de Live procesan pagos reales contra el procesador. Solo usa keys de Live cuando tu integracion este completamente validada.

API keys de Test

Las API keys de Test permiten probar toda la integracion sin mover dinero real. Los pagos se simulan, los webhooks se generan automaticamente, y los datos se almacenan de forma completamente aislada.

Flujo de integracion recomendado: Empieza siempre con una API key de Test. Desarrolla y valida toda tu integracion. Cuando todo funcione correctamente, crea una API key de Live y cambia las URLs (anade o quita /test/).

Restriccion por IP

Las API keys pueden tener restricciones de IP configuradas desde el dashboard. Si tu IP no esta en la lista permitida, recibiras un error 403 Forbidden.

Recomendacion: Configura restricciones de IP en produccion para mayor seguridad. En el entorno Test, puedes dejar las IPs sin restriccion para facilitar el desarrollo.

Restriccion por webcode

Cada API key esta vinculada a un webcode especifico (identificador de tu negocio en Avirato Payments). Solo puedes operar con el webcode asociado a tu key.

El campo webcode es obligatorio en todas las peticiones y debe coincidir con el webcode de tu API key. En POST/PATCH va en el body; en GET, como parametro de query (?webcode=SHOP01).

En pagos recurrentes solo ves y modificas los de tu webcode y del mismo entorno de la key. Uno de otro webcode o del otro entorno responde 404, como si no existiera.

Scopes

Las API keys tienen un scope que determina a que endpoints pueden acceder:

Una key de Live no puede acceder a rutas de Test, y viceversa.

Idempotencia

Los endpoints de escritura (crear sesion, modificaciones, pago POS y todos los POST/PATCH de pagos recurrentes) soportan la cabecera Idempotency-Key. Si envias la misma Idempotency-Key con los mismos parametros:

1. La primera peticion se procesa normalmente
2. Las siguientes peticiones con la misma key devuelven la misma respuesta sin ejecutar la operacion de nuevo

La idempotencia funciona de forma identica en ambos entornos (Live y Test). Los registros de idempotencia de cada entorno estan aislados entre si.

Conflictos de idempotencia (409)

Si reutilizas una Idempotency-Key de forma incorrecta, la API responde con 409 Conflict para evitar comportamientos inconsistentes:

Recomendacion: usa Idempotency-Key siempre en produccion para evitar cobros duplicados, pero asocia una clave unica por intento logico (por ejemplo, derivada del orderId + retry). Si necesitas modificar el body, usa una clave nueva.

# Primera llamada: crea el pago
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Segunda llamada con la misma key y mismo body: devuelve la misma respuesta sin crear otro pago
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 10000, "currency": "EUR" }, ... }'

# Tercera llamada con la misma key pero distinto body: 409 Conflict
curl -X POST .../payment/session \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{ "webcode": "SHOP01", "amount": { "value": 99999, "currency": "EUR" }, ... }'

Client Secret

Cada entorno tiene su propio client secret. El client secret se usa para descifrar los datos cifrados que llegan en el redirect post-pago (parametro data en la urlOk).

• Client secret de Live: se genera al crear la primera API key de Live.
• Client secret de Test: se genera al crear la primera API key de Test.

El client secret solo se muestra una vez al momento de crear la primera key del entorno. Si lo pierdes, puedes rotarlo desde el dashboard (seccion Integraciones > Configuracion > API keys > Rotar Secret).

Importante: Los client secrets de Live y Test son diferentes. Asegurate de usar el secret correcto para descifrar los datos del redirect en cada entorno.

Gestion de API keys

Las API keys se gestionan desde el Dashboard de Avirato Payments (seccion Integraciones > Configuracion > API keys):

Pagos online

Concepto clave: Sesion vs pago

Es fundamental entender que en la External API existen dos conceptos distintos: la sesion y el pago. Aunque estan relacionados, representan cosas diferentes y tienen ciclos de vida independientes.

La sesion (sessionId)

La sesion es lo que tu sistema crea al llamar a POST /payment/session. Representa la intencion de cobro: el importe, la divisa, las URLs de retorno, la descripcion, etc. Cuando la creas, recibes un sessionId y una paymentUrl para redirigir al cliente.

Cuando el cliente completa el pago con exito, la sesion pasa a estado completed y se cierra.

La sesion no se modifica una vez completada. Su trabajo ha terminado: sirvio para que el cliente pagara.

El pago (paymentReference)

El pago es la transaccion real que se crea cuando el cliente completa satisfactoriamente el formulario de pago. Es el objeto que el procesador de pagos reconoce y sobre el que se pueden hacer operaciones.

El paymentReference (referencia del pago autorizado) aparece dentro de la sesion una vez completada, en el campo paymentReference y tambien en el array de attempts.

El pago es lo que importa para operaciones posteriores. Reembolsos, capturas, cancelaciones y extensiones se hacen sobre el paymentReference, no sobre el sessionId.

Relacion visual

En resumen

Regla practica: Usa sessionId para consultar el estado y obtener el paymentReference. Usa paymentReference para modificar el pago (refund, capture, cancel, extend).

Flujo completo de un pago online

Antes de entrar en los endpoints, es importante entender el flujo completo. Un pago online implica tres participantes y tres redireccionamientos:

Paso a paso

1. Tu sistema crea la sesion llamando a POST /payment/session con el importe, la divisa, y dos URLs de retorno: urlOk y urlKo
2. Recibes un sessionId y una paymentUrl. La paymentUrl es un enlace a la pagina de pago segura de Avirato Payments
3. Redirige al cliente a la paymentUrl. Puedes hacer un redirect HTTP 302 o abrir en una nueva pestana, segun tu caso de uso
4. El cliente ve la pagina de pago. Ahi introduce su tarjeta, completa 3D Secure si es necesario, y confirma el pago. Tu sistema no interviene en este paso
5. Avirato Payments redirige automaticamente al cliente a una de las dos URLs que proporcionaste:
   • urlOk si el pago se completo con exito
   • urlKo si el pago fallo, fue cancelado por el cliente, o expiro
6. El cliente llega a tu pagina. En la urlOk puedes mostrar un mensaje de confirmacion. En la urlKo puedes informar del problema y, si tiene sentido, crear una nueva sesion de pago para ofrecer otro intento
7. Tu sistema confirma el pago usando las herramientas que te proporcionamos: los datos cifrados que llegan en el parametro data de la urlOk (descifrables con tu client secret), el webhook que recibiras automaticamente unos segundos despues, y opcionalmente la consulta GET /payment/session/{id} para verificacion adicional

Entorno Test: El flujo es identico. La unica diferencia es que en el paso 4, la pagina de pago es un formulario simulado (no conecta con ningun procesador real). El cliente introduce tarjetas ficticias y el resultado se determina segun el nombre del titular (ver Tarjetas de prueba).

La importancia de urlOk y urlKo

Estas dos URLs son el puente de vuelta entre nuestra pagina de pago y tu sistema. Son obligatorias y determinan la experiencia del cliente despues de pagar:

• urlOk: Donde aterrizara el cliente cuando el pago sea exitoso. Debe ser una pagina de tu sistema que muestre una confirmacion (ej: "Gracias, tu pago se ha completado"). La URL recibira un parametro data con informacion cifrada del pago (descifrable con tu client secret)
• urlKo: Donde aterrizara el cliente si algo falla (tarjeta rechazada, timeout, cancelacion). Debe ser una pagina que informe del problema. Si quieres ofrecer otro intento, crea una nueva sesion de pago desde tu backend y redirige al cliente a la nueva paymentUrl

Recomendacion practica: Usa el campo customReference al crear la sesion para incluir tu referencia interna (ej: numero de pedido, ID de operacion). Este valor se incluye en los datos cifrados del redirect y en los webhooks, lo que te permite asociar automaticamente el resultado con la operacion original en tu sistema.

No confies solo en la URL de retorno: verifica el estado con GET /payment/session/{sessionId} y, sobre todo, con los webhooks. En Live el estado definitivo de un pago puede evolucionar despues del redirect o de una consulta anterior (por ejemplo, un chargeback notificado por el procesador). Trata los webhooks como la referencia de negocio para cambios tardios y vuelve a consultar la API si necesitas el estado persistido (ver Webhooks).

Crear sesion de pago

Crea una sesion de pago y obtiene una URL donde redirigir al cliente para completar el pago.

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

Parametros del body

Ejemplo de peticion (Live)

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false
  }'

Ejemplo de peticion (Test)

curl -X POST https://aviratopayments.com/external/v1/test/payment/session \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345"
  }'

Respuesta exitosa (201)

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "paymentUrl": "https://aviratopayments.com/pay-external/eyJhbGciOi...",
    "status": "pending",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "createdAt": "2026-06-28 10:30:00"
  }
}

Formato de sessionId: En Live el formato es {webcode}-EXT-{timestamp}. En Test el formato es {webcode}-EXTT-{timestamp}. Esto te permite identificar a simple vista de que entorno proviene una sesion.

paymentUrl en Test: La URL apunta a una pagina de pago simulada (no conecta con la pasarela real). El formulario acepta tarjetas ficticias y el resultado se determina por el nombre del titular. Ver Tarjetas de prueba.

Que hacer con la respuesta

1. Guarda el sessionId en tu sistema, asociado a la operacion (pedido, servicio, etc.). Lo necesitaras para consultar el estado y obtener el paymentReference cuando se complete
2. Redirige al cliente a paymentUrl inmediatamente. Ahi vera la pagina de pago segura con los metodos de pago disponibles
3. Prepara tus paginas de retorno (urlOk y urlKo). El cliente llegara a una de ellas despues de pagar

Tiempo limite para pagar

Una vez que el cliente abre la paymentUrl, dispone de 5 minutos (300 segundos) para completar el pago. Pasado ese tiempo, la pagina de pago expira automaticamente y el cliente es redirigido a urlKo.

La sesion en si no tiene un tiempo de expiracion fijo desde el servidor: lo que expira es la pagina de pago en el navegador del cliente. Si el cliente no abre la paymentUrl, la sesion permanece en estado pending indefinidamente.

La pagina de pago muestra un reloj con la cuenta atras visible para el cliente, asi que no necesitas informarle por tu parte.

Ciclo de vida de la sesion

La sesion (no el pago) pasa por estos estados:

Importante: Una sesion completed no cambiara de estado. A partir de ese momento, lo relevante es el pago (paymentReference), que es el que puedes reembolsar, capturar, etc.

Si el pago falla

Si el pago falla (tarjeta rechazada, 3DS cancelado, timeout), el cliente es redirigido a tu urlKo. Para ofrecer otro intento, crea una nueva sesion y redirige al cliente a la nueva paymentUrl.

URLs de prueba: Las URLs urlOk y urlKo del ejemplo apuntan a paginas de prueba del dashboard, pensadas para que puedas analizar el mensaje de respuesta y verificar el descifrado con tu client secret. Puedes sustituirlas por las URLs de tu propio sistema.

Redirect post-pago: lo que ocurre cuando el cliente termina

Una vez que el cliente completa el formulario de pago (o lo abandona/falla), Avirato Payments le redirige automaticamente a la URL correspondiente:

• Pago exitoso -> el cliente es redirigido a tu urlOk
• Pago fallido, cancelado o expirado -> el cliente es redirigido a tu urlKo

La redireccion es automatica: el cliente ve brevemente un mensaje "Redirigiendo..." y aterriza en tu pagina sin necesidad de hacer clic en ningun boton.

El parametro data en urlOk

Cuando el cliente llega a tu urlOk, la URL incluye un parametro data con un JWT que contiene informacion cifrada del pago:

https://tu-sistema.com/pago-ok?data=eyJhbGciOiJIUzI1NiIs...

Para leer esta informacion:

1. Extrae el parametro data de la URL
2. Decodifica el JWT usando tu client secret como clave (ver Autenticacion - Client Secret)
3. El payload descifrado contiene los datos del pago: referencia, importe, estado, etc.

urlKo no incluye el parametro data, ya que no hay pago exitoso del que informar. En urlKo muestra un mensaje apropiado al cliente.

Entorno Test: El parametro data en urlOk funciona exactamente igual que en Live. Se cifra con el client secret del entorno Test, y lo descifras con ese mismo secret. El contenido tiene la misma estructura.

Validacion de los datos del redirect

Cuando recibas al cliente en urlOk con el parametro data, valida la informacion cifrada contra los datos en abierto:

1. Decodifica el JWT con tu client secret
2. Compara los datos del payload (importe, referencia, estado) con lo que esperas segun tu logica de negocio
3. Si los datos no coinciden, trata la operacion como sospechosa

Esto protege contra manipulaciones: un usuario podria cambiar la URL manualmente, pero no puede falsificar el JWT sin tu client secret.

Que pasa si el cliente cierra el navegador

Si el cliente completa el pago pero cierra el navegador antes de ser redirigido, el pago se ha completado igualmente.

En este caso, el cliente nunca llega a tu urlOk. Para cubrir este escenario:

1. Recibiras un webhook unos segundos despues de que el pago se complete (ver Webhooks)
2. Como alternativa, puedes hacer polling periodico con GET /payment/session/{sessionId} para detectar sesiones que pasaron a completed sin que el cliente volviera

Recomendacion: No dependas exclusivamente de la redireccion a urlOk para confirmar pagos. Usa los webhooks como fuente principal de confirmacion y la redireccion como mejora de experiencia de usuario.

Tarjetas de prueba (entorno Test)

En el entorno Test, la pagina de pago es un formulario simulado. No se conecta con ningun procesador real. El resultado del pago se determina por el nombre del titular de la tarjeta (holderName):

Pago exitoso

Usa cualquier nombre que no sea uno de los valores especiales de la tabla siguiente. Ejemplo: Juan Garcia, Test User, Maria Lopez.

Simular fallos

Datos de la tarjeta

El formulario simulado valida el formato de la tarjeta de forma realista:

• Numero: Debe tener 13-19 digitos y pasar la validacion Luhn. Ejemplo: 4111 1111 1111 1111 (Visa)
• Mes de expiracion: Formato MM (01-12), no puede estar expirada
• Ano de expiracion: Formato YY (2 digitos), no puede estar expirado
• CVC: 3 digitos (Visa/Mastercard) o 4 digitos (Amex)
• Nombre del titular: Minimo 3 caracteres

Tip: Para probar un flujo exitoso rapido, usa 4111 1111 1111 1111, expiracion 12/30, CVC 737, nombre Test User.

Preautorizaciones

Si necesitas reservar un importe sin capturarlo inmediatamente (ej: deposito de garantia), usa isPreAuth: true.

Con una preautorizacion puedes despues:

• Capturar el importe total o parcial: POST /payment/capture
• Cancelar la preautorizacion: POST /payment/cancel
• Extender el plazo antes de que expire: POST /payment/extend

Ver Modificaciones para mas detalle.

Divisas aceptadas

Actualmente la External API acepta las siguientes divisas:

Si envias un codigo de divisa no soportado, recibiras un error 400 Bad Request.

Errores comunes

Pagos POS (terminal fisico)

Los pagos POS permiten enviar un cobro directamente a un terminal fisico (TPV) conectado. El flujo es sincrono: la respuesta llega cuando el terminal procesa el pago (o expira por timeout).

Listar terminales

Antes de enviar un pago POS, necesitas conocer el identificador del terminal (poiId).

Live: GET https://aviratopayments.com/external/v1/pos/terminals?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/pos/terminals?webcode={webcode}

Parametros de query

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-123456789",
      "status": "boarded",
      "name": "Mostrador Principal",
      "model": "V400m",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-20T08:30:00Z"
    }
  ]
}

Solo se devuelven terminales con estado boarded (activos y operativos).

• Con syncFromProvider=false (por defecto): devuelve todos los terminales registrados como boarded.
• Con syncFromProvider=true: solo devuelve los terminales que ademas estan actualmente conectados (online). Util para saber que terminales estan operativos en tiempo real.

Entorno Test: Se devuelven 3 terminales simulados, todos con estado boarded:

Con syncFromProvider=true, solo se devuelven los 2 terminales online. El terminal offline (P400Plus-TEST-000003) permite probar el error DeviceError (502, code 13004) al intentar cobrar en un terminal no conectado.

Solo se aceptan los poiId de esta lista para enviar pagos POS en Test. Usar un poiId no listado devolvera error 400.

Crear pago POS

Envia un cobro a un terminal fisico. La peticion espera a que el terminal procese el pago.

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

Parametros del body

Ejemplo (Live)

curl -X POST https://aviratopayments.com/external/v1/pos/payment \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-sale-67890" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628"
  }'

Respuesta exitosa (200)

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSX-1719500000",
    "paymentReference": "SHOP01-POSX-1719500000",
    "poiId": "V400m-123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "KVGQSN3K2SKFNVNS",
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628",
    "createdAt": "2026-06-28 14:15:00"
  }
}

Formato de posPaymentId: En Live el formato es {webcode}-POSX-{timestamp}. En Test el formato es {webcode}-POSXT-{timestamp}.

Timeout recomendado: Configura un timeout de al menos 240 segundos tanto en tu cliente HTTP como en tu servidor (por ejemplo, max_execution_time en PHP, proxy_read_timeout en Nginx, o el equivalente en tu stack). La peticion espera a que el cliente interactue con el terminal (insertar tarjeta, introducir PIN, etc.), lo cual puede tardar. Si tu servidor corta la conexion antes de recibir la respuesta, no recibiras el resultado directo — aunque el pago puede completarse igualmente en segundo plano.

Estados del pago POS

Manejo de timeouts

Si el terminal no responde dentro del tiempo limite, la respuesta tendra status: "timeout". En este caso:

1. No reintentes inmediatamente: el pago podria estar en proceso
2. Usa Idempotency-Key: si reenvias la peticion con la misma key, recibiras la respuesta almacenada
3. Consulta el estado: usa GET /pos/payments para verificar si el pago llego a completarse
4. El webhook llega igualmente: Si el pago se completa despues del timeout, recibiras un webhook de confirmacion (AUTHORISATION) con el resultado final. Implementa webhooks como red de seguridad para no perder pagos completados que no pudiste capturar en la respuesta sincrona.

Errores especificos de POS

Todos los errores de POS siguen el formato estandar de error:

{
  "success": false,
  "error": {
    "message": "Terminal is busy processing another payment",
    "code": 13005,
    "statusCode": 409,
    "traceId": "abc123def456..."
  }
}

Simulacion POS en entorno Test

En el entorno Test, los pagos POS no se envian a un terminal real. El sistema valida el poiId contra la lista de terminales simulados y determina el resultado.

Terminales simulados

Solo se aceptan los poiId devueltos por GET /test/pos/terminals. Si envias un poiId que no esta en la lista, recibiras error 400.

Si envias un pago al terminal offline (P400Plus-TEST-000003), se simula el error real que devuelve el procesador cuando un terminal no esta conectado:

{
  "success": false,
  "error": {
    "message": "Error in POS payment response: Reject",
    "code": 13004,
    "statusCode": 502,
    "traceId": "..."
  }
}

Para los terminales online (V400m-TEST-000001, S1F2-TEST-000002), el resultado se determina por los ultimos dos digitos del importe (amount.value):

Magic amounts (ultimos 2 digitos del importe)

Ejemplos

Importante: En Test, la respuesta incluye un pequeno delay simulado (2-3 segundos) para emular el tiempo de comunicacion con el terminal.

Webhooks en Test: Cuando un pago POS se completa (exito o fallo) en entorno Test, se genera automaticamente un webhook simulado que se envia a tu URL de webhook, igual que ocurriria en Live cuando el procesador confirma la operacion.

Listar pagos POS

Consulta el historial de pagos POS con filtros y paginacion basada en cursor.

Live: GET https://aviratopayments.com/external/v1/pos/payments?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/pos/payments?webcode={webcode}

Parametros de query

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/pos/payments?webcode=SHOP01&status=success&take=10" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": {
    "posPayments": [
      {
        "posPaymentId": "SHOP01-POSX-1719500000",
        "paymentReference": "SHOP01-POSX-1719500000",
        "poiId": "V400m-123456789",
        "amount": { "value": 5000, "currency": "EUR" },
        "status": "success",
        "isPreAuth": false,
        "pspReference": "KVGQSN3K2SKFNVNS",
        "description": "Venta mostrador #205",
        "customReference": "VENTA-205-20260628",
        "createdAt": "2026-06-28 14:15:00"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NDJ9",
      "hasMore": true,
      "total": 156
    }
  }
}

Paginacion

La paginacion usa cursores en lugar de numeros de pagina:

1. La primera peticion se hace sin cursor
2. Si meta.hasMore es true, usa el valor de meta.cursor como parametro cursor en la siguiente peticion
3. Repite hasta que meta.hasMore sea false

# Pagina 1
curl ".../pos/payments?webcode=SHOP01&take=20"

# Pagina 2 (usando el cursor de la respuesta anterior)
curl ".../pos/payments?webcode=SHOP01&take=20&cursor=eyJpZCI6NDJ9"

Diferencias entre pagos online y POS

Pagos Recurrentes

Cobra a tus clientes de forma periodica (mensual, semanal, cada N dias, anual, un dia concreto de cada mes, con o sin fecha de fin) y gestiona todo el ciclo de vida desde tu sistema: alta, consulta, cambios, pausa, reactivacion, cambio de tarjeta y cancelacion.

Nombre tecnico: en la API cada pago recurrente es un recurso subscription (rutas /subscriptions, ids WEBCODE-SB-xxxxxxxx). En el panel aparecen en Transacciones > Pagos Recurrentes.

Reglas generales

• webcode obligatorio: en el body en POST/PATCH y en la query en GET. Debe coincidir con el de tu API key.
• Solo veras y modificaras los pagos recurrentes de tu webcode y de ese entorno. Cualquier recurso ajeno o del otro entorno responde 404.
• Importes siempre en centimos (2990 = 29,90 EUR). Monedas: EUR, USD, GBP.
• Idempotency-Key recomendada en todos los POST y PATCH (ver Autenticacion).

Flujo

1. POST /subscriptions crea un link de pago recurrente y devuelve paymentUrl.
2. Rediriges a tu cliente a paymentUrl. Paga el primer importe y se guarda su tarjeta.
3. Se crea el pago recurrente (subscriptionId) y recibes SUBSCRIPTION_CREATED. Tambien puedes consultarlo en GET /subscriptions/links/{linkId} (campo subscriptionId).
4. Avirato cobra cada periodo. Si un cobro falla se reintenta 3 veces (5 h, 8 h y 11 h despues); si sigue fallando el pago recurrente queda pausado (SUBSCRIPTION_ERROR).

Si el primer pago se rechaza

Se crea igualmente el pago recurrente en estado error (statusReason: initial_payment_failed) y recibes SUBSCRIPTION_FAILED. El link sigue pending y tu cliente puede reintentar con el mismo paymentUrl: cada intento crea un pago recurrente nuevo. El anterior queda en error, nunca se cobra y puedes ignorarlo. El valido es el del webhook SUBSCRIPTION_CREATED, que es tambien el que devuelve el detalle del link. El motivo del rechazo esta en refusalReason de GET /subscriptions/{id}/payments. Igual en Live y en Test.

Intervalos

• intervalCount minimo 1.
• billingDay (1-31) solo con month. En meses mas cortos se cobra el ultimo dia del mes.
• endAt futura (Y-m-d o Y-m-d H:i:s): el dia de fin ya no se cobra; esa noche el pago recurrente se cancela (statusReason: end_date_reached).
• initialAmount: primer pago distinto al recurrente (puede ser 0 para solo guardar la tarjeta).

Crear un pago recurrente

POST /external/v1/subscriptions → 201

{
  "webcode": "SHOP01",
  "amount": { "value": 2990, "currency": "EUR" },
  "intervalUnit": "month",
  "intervalCount": 1,
  "billingDay": 5,
  "endAt": "2027-06-30",
  "initialAmount": { "value": 990 },
  "returnUrl": "https://tu-web.com/pago-recurrente/ok",
  "description": "Plan Gold",
  "customReference": "PEDIDO-123",
  "planCode": "GOLD",
  "customerInternalId": "CLI-42",
  "customerInternalFolder": "EXP-2026-7",
  "customerExtraInfo": "Juan Perez",
  "metadata": { "contrato": "C-99" },
  "expiresAt": "2026-11-30 23:59:59",
  "countryCode": "ES",
  "shopperLocale": "es-ES"
}

Obligatorios: webcode, amount, intervalUnit, intervalCount, returnUrl (http/https). description maximo 255 caracteres; metadata debe ser un objeto JSON.

{
  "success": true,
  "data": {
    "linkId": "SHOP01-LK-1792068995050",
    "environment": "live",
    "status": "pending",
    "paymentUrl": "https://aviratopayments.com/pay/eyJ0eXAi...",
    "subscriptionId": null,
    "amount": { "value": 2990, "currency": "EUR" },
    "initialAmount": { "value": 990, "currency": "EUR" },
    "intervalUnit": "month",
    "intervalCount": 1,
    "billingDay": 5,
    "endAt": "2027-06-30 23:59:59",
    "planCode": "GOLD",
    "returnUrl": "https://tu-web.com/pago-recurrente/ok",
    "expiresAt": "2026-11-30 23:59:59",
    "createdAt": "2026-10-15 14:56:35"
  }
}

Al terminar el pago el cliente vuelve a returnUrl con ?linkId=...&subscriptionId=...&status=success|refused|error. No te fies solo del redirect: confirma con el webhook o consultando el link.

Endpoints

Consultas

Ciclo de vida (body siempre con webcode)

Estados y acciones permitidas

Entorno Test

Todo funciona igual que en Live pero sin dinero real. Los pagos recurrentes de test no aparecen en el panel; consultalos con la API.

Pago inicial: abre paymentUrl (/pay-subscription-test/...) y usa cualquier tarjeta valida (p. ej. 4111 1111 1111 1111, fecha futura en formato MM/AA, CVC 737). El titular decide el resultado:

Simuladores (solo /external/v1/test/...), body { "webcode", "result" } con result: success (def.), declined, not_enough_balance, card_expired, error:

Webhooks

Eventos SUBSCRIPTION_CREATED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_FAILED, SUBSCRIPTION_ERROR, SUBSCRIPTION_PAUSED, SUBSCRIPTION_REACTIVATED, SUBSCRIPTION_CANCELLED y SUBSCRIPTION_CARD_UPDATED. Formato y ejemplos en Webhooks.

Errores habituales

Ver Errores > Pagos recurrentes. Resumen: 400 validacion o accion no permitida en el estado actual, 403 key/webcode/entorno, 404 no existe para tu webcode y entorno, 409 Idempotency-Key reutilizada.

Modificaciones de pago

Las modificaciones permiten operar sobre pagos ya completados (tanto online como POS). Todos los endpoints de modificacion devuelven HTTP 202 Accepted porque la operacion se procesa de forma asincrona por el procesador de pagos.

Sesion vs pago: recordatorio importante

Las modificaciones no operan sobre la sesion (sessionId), sino sobre el pago (paymentReference). La sesion es el contenedor que se crea al llamar a POST /payment/session; el pago es la transaccion real que se crea cuando el cliente paga con exito. Una vez completada la sesion, esta no cambia mas: lo que importa a partir de ese momento es el pago.

Para mas detalle sobre esta distincion, ver Sesion vs pago.

Como obtener el paymentReference

Todas las modificaciones requieren un paymentReference que identifica el pago real:

• Para pagos online: consulta la sesion con GET /payment/session/{sessionId}. Cuando la sesion esta completed, el campo paymentReference contiene la referencia del pago autorizado
• Para pagos POS: es el paymentReference que se devuelve directamente en la respuesta de POST /pos/payment (coincide con el posPaymentId)

Ambos tipos de referencia funcionan indistintamente en todos los endpoints de modificacion.

Reembolso (refund)

Devuelve total o parcialmente el importe de un pago completado.

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

Parametros del body

Valores permitidos para reason

Importante: Los valores son case-sensitive e incluyen espacio en CUSTOMER REQUEST. Enviar customer request o Customer Request producira un error 400.

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/refund \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-12345" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Respuesta (202)

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195234567890",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "status": "pending",
    "createdAt": "2026-06-29 14:00:00"
  }
}

El refundReference (formato {webcode}-RFX-{timestamp} en Live, {webcode}-RFXT-{timestamp} en Test) identifica esta operacion de reembolso. Usalo para seguimiento en el listado de modificaciones.

Reembolso parcial vs total

Puedes reembolsar cualquier importe menor o igual al importe original del pago. Si necesitas hacer multiples reembolsos parciales sobre el mismo pago, puedes hacerlo siempre que la suma total no supere el importe original.

Captura (capture)

Captura total o parcialmente una preautorizacion (pago creado con isPreAuth: true).

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

Parametros del body

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/capture \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capture-preauth-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    }
  }'

Respuesta (202)

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195345678901",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 15:00:00"
  }
}

El captureReference (formato {webcode}-CTX-{timestamp} en Live, {webcode}-CTXT-{timestamp} en Test) identifica esta operacion de captura.

Captura parcial

Si preautorizaste 500 EUR pero el importe final del servicio fue 450 EUR, puedes capturar solo 45000 centimos. La diferencia se libera automaticamente.

Captura excedente

Si intentas capturar un importe superior al preautorizado, la peticion se acepta (HTTP 202) pero el procesador rechazara la operacion. Recibiras un webhook con result: "failure" indicando que el importe excede el autorizado.

Cancelacion (cancel)

Cancela una preautorizacion antes de que se capture. Libera los fondos retenidos en la tarjeta del cliente.

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

Parametros del body

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/cancel \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-preauth-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Respuesta (202)

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195456789012",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "status": "received",
    "createdAt": "2026-06-29 16:00:00"
  }
}

El cancelReference (formato {webcode}-CAX-{timestamp} en Live, {webcode}-CAXT-{timestamp} en Test) identifica esta operacion de cancelacion.

Extension (extend)

Extiende el plazo de una preautorizacion antes de que expire. Las preautorizaciones tienen una validez limitada (normalmente 7-28 dias segun el banco emisor). Si necesitas mas tiempo, puedes extenderla. La extension amplia el plazo 28 dias adicionales contando desde el momento en que se solicita.

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

Parametros del body

No se necesita enviar importe ni divisa: la extension mantiene el importe original.

Ejemplo

curl -X POST https://aviratopayments.com/external/v1/payment/extend \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: extend-preauth-22222" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Respuesta (202)

{
  "success": true,
  "data": {
    "updateReference": "SHOP01-UPX-17195567890123",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 17:00:00"
  }
}

El updateReference (formato {webcode}-UPX-{timestamp} en Live, {webcode}-UPXT-{timestamp} en Test) identifica esta operacion de extension. El amount devuelto es el importe original del pago.

Estado de las modificaciones

Las modificaciones se procesan de forma asincrona. El estado devuelto en la respuesta inicial depende de la operacion y evoluciona conforme el procesador confirma:

Nota sobre los estados iniciales: Las operaciones de refund devuelven pending porque el reembolso puede tardar en procesarse. Capture, cancel y extend devuelven received porque la confirmacion del procesador es mas rapida. En ambos casos, el estado final sera success o failed.

Como saber cuando se completa una modificacion:

1. Webhooks (recomendado): Recibiras un webhook automatico cuando el procesador confirme la operacion. Ver Webhooks para detalles del formato y ejemplos
2. Consulta: Puedes consultar el estado actualizado con Listar modificaciones

Modificaciones en entorno Test

En el entorno Test, las modificaciones se procesan de forma simulada e inmediata. No se contacta con ningun procesador real. El backend genera un webhook simulado con el resultado (success o failed) que se envia a tu URL de webhook en segundos.

Comportamiento simulado por tipo

Importante: En Test, el webhook de confirmacion se genera automaticamente en el momento de la peticion. En Live, el webhook llega cuando el procesador real confirma la operacion (segundos a minutos).

Referencia rapida de marcadores

Cada tipo de modificacion genera una referencia con un prefijo identificativo:

Errores comunes en modificaciones

Consultas

Obtener detalle de un pago

Obtiene la informacion completa de una sesion de pago online, incluyendo todos los intentos de pago y, si la sesion esta completada, la referencia del pago autorizado (paymentReference).

Este endpoint es la forma principal de obtener el paymentReference que necesitas para realizar modificaciones (reembolsos, capturas, etc.).

Live: GET https://aviratopayments.com/external/v1/payment/session/{sessionId}?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/payment/session/{sessionId}?webcode={webcode}

Parametros

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200) - sesion completada

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "status": "completed",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "deliverAt": "2026-07-15T14:00:00Z",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "createdAt": "2026-06-28 10:30:00",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "completedAt": "2026-06-28 10:35:22",
    "paymentStatus": "AUTHORISED",
    "attempts": [
      {
        "paymentReference": "SHOP01-PXT-17195000003456",
        "status": "refused",
        "createdAt": "2026-06-28 10:32:00"
      },
      {
        "paymentReference": "SHOP01-PXT-17195000005678",
        "status": "authorised",
        "createdAt": "2026-06-28 10:34:00"
      }
    ]
  }
}

Respuesta (200) - sesion pendiente

Cuando la sesion aun no se ha completado, no incluye paymentReference, completedAt ni paymentStatus:

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "status": "pending",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "deliverAt": "2026-07-15T14:00:00Z",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "createdAt": "2026-06-28 10:30:00",
    "attempts": []
  }
}

Campos de respuesta

Errores

Listar pagos

Lista todas las sesiones de pago online con filtros y paginacion basada en cursor.

Live: GET https://aviratopayments.com/external/v1/payment/sessions?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/payment/sessions?webcode={webcode}

Parametros de query

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=10" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": {
    "payments": [
      {
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "completed",
        "amount": { "value": 15000, "currency": "EUR" },
        "description": "Pedido #12345",
        "customReference": "ORD-2026-12345",
        "isPreAuth": false,
        "createdAt": "2026-06-28 10:30:00",
        "completedAt": "2026-06-28 10:35:22",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "paymentStatus": "AUTHORISED"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NDJ9",
      "hasMore": true,
      "total": 89
    }
  }
}

Campos de cada sesion en el listado

Paginacion con cursores

La paginacion funciona con cursores opacos (no numeros de pagina):

# Primera pagina
GET .../payment/sessions?webcode=SHOP01&take=20

# Siguiente pagina (usando cursor de meta.cursor)
GET .../payment/sessions?webcode=SHOP01&take=20&cursor=eyJpZCI6NDJ9

# Repetir hasta meta.hasMore == false

Los cursores son cadenas opacas. No intentes decodificarlos ni construirlos manualmente; simplemente pasa el valor de meta.cursor tal cual.

Listar modificaciones de un pago

Lista todas las operaciones de modificacion (refund, capture, cancel, extend) asociadas a una sesion de pago online.

Live: GET https://aviratopayments.com/external/v1/payment/session/{sessionId}/modifications?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/payment/session/{sessionId}/modifications?webcode={webcode}

Parametros

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195100001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "success",
        "requestedAt": "2026-06-29 14:00:00",
        "createdAt": "2026-06-29 14:00:00",
        "resolvedAt": "2026-06-29 14:00:05",
        "amount": {
          "value": 5000,
          "currency": "EUR"
        },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": null,
      "hasMore": false,
      "total": 1
    }
  }
}

Campos de cada modificacion

Listar modificaciones de un pago POS

Lista todas las operaciones de modificacion asociadas a un pago POS especifico.

Live: GET https://aviratopayments.com/external/v1/pos/payment/{posPaymentId}/modifications?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/pos/payment/{posPaymentId}/modifications?webcode={webcode}

Parametros

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/pos/payment/SHOP01-POSX-17195300001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195400001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-POSX-17195300001234",
        "sessionId": "SHOP01-POSX-17195300001234",
        "status": "success",
        "requestedAt": "2026-06-30 10:00:00",
        "createdAt": "2026-06-30 10:00:00",
        "resolvedAt": "2026-06-30 10:00:03",
        "amount": {
          "value": 2000,
          "currency": "EUR"
        },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": null,
      "hasMore": false,
      "total": 1
    }
  }
}

Los campos de respuesta son identicos a los de Listar modificaciones de un pago.

Errores

Listar todas las modificaciones

Lista todas las operaciones de modificacion de tu negocio, independientemente del pago al que pertenezcan. Permite filtrar por tipo, estado, fecha y texto libre.

Live: GET https://aviratopayments.com/external/v1/modifications?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/modifications?webcode={webcode}

Parametros de query

Ejemplo

curl -X GET "https://aviratopayments.com/external/v1/modifications?webcode=SHOP01&type=refund&status=success&take=10" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200)

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195100001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "success",
        "requestedAt": "2026-06-29 14:00:00",
        "createdAt": "2026-06-29 14:00:00",
        "resolvedAt": "2026-06-29 14:00:05",
        "amount": {
          "value": 5000,
          "currency": "EUR"
        },
        "reason": "CUSTOMER REQUEST"
      },
      {
        "operationReference": "SHOP01-RFX-17195400001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-POSX-17195300001234",
        "sessionId": "SHOP01-POSX-17195300001234",
        "status": "success",
        "requestedAt": "2026-06-30 10:00:00",
        "createdAt": "2026-06-30 10:00:00",
        "resolvedAt": "2026-06-30 10:00:03",
        "amount": {
          "value": 2000,
          "currency": "EUR"
        },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NDJ9",
      "hasMore": false,
      "total": 2
    }
  }
}

Este endpoint devuelve modificaciones de todos los pagos (online y POS). Puedes identificar el tipo de pago por la referencia: -PXT- (pago online Live), -PXTT- (pago online Test), -POSX- (POS Live), -POSXT- (POS Test).

Paginacion

Todos los endpoints de listado usan paginacion basada en cursores. Los cursores son cadenas opacas que representan la posicion actual en el conjunto de resultados.

Como funciona

1. Primera peticion: Llama al endpoint sin parametro cursor. Recibiras los primeros resultados y un meta.cursor
2. Siguiente pagina: Si meta.hasMore es true, usa el valor de meta.cursor como parametro cursor en la siguiente peticion
3. Fin: Cuando meta.hasMore es false, no hay mas resultados

Campos de meta

Ejemplo de navegacion

# Pagina 1
curl ".../payment/sessions?webcode=SHOP01&take=10"
# meta: { "cursor": "eyJpZCI6MTB9", "hasMore": true, "total": 45 }

# Pagina 2
curl ".../payment/sessions?webcode=SHOP01&take=10&cursor=eyJpZCI6MTB9"
# meta: { "cursor": "eyJpZCI6MjB9", "hasMore": true, "total": 45 }

# Pagina 3
curl ".../payment/sessions?webcode=SHOP01&take=10&cursor=eyJpZCI6MjB9"
# meta: { "cursor": null, "hasMore": false, "total": 45 }

Importante: Los cursores son opacos. No intentes decodificarlos, modificarlos ni construirlos manualmente. Simplemente pasa el valor tal cual lo recibes.

Webhooks

Los webhooks son notificaciones HTTP POST que Avirato Payments envia automaticamente a tu sistema cuando ocurre un evento relevante: un pago se completa, un reembolso se procesa, una captura se confirma, etc.

Por que son importantes

Los webhooks son la forma mas fiable de saber que una operacion se ha completado. A diferencia del redirect (urlOk/urlKo), que depende de que el cliente vuelva a tu pagina:

• Los webhooks llegan siempre, incluso si el cliente cierra el navegador
• Llegan unos segundos despues de que el procesador confirme la operacion
• No dependen del comportamiento del usuario

Recomendacion: Usa los webhooks como fuente principal de confirmacion de operaciones. Usa el redirect y el polling como complementos.

Como configurar tu URL de webhooks

Desde Integraciones > Configuración > URLs de webhooks puedes registrar una URL pública por entorno (Live y Test). Cada URL puede activarse y desactivarse por separado. Recomendamos:

• URL HTTPS (no HTTP) con certificado válido.
• Endpoint dedicado a Avirato Payments (por ejemplo https://tu-dominio.com/avirato-payments/webhooks) que sepa procesar el formato común que se describe más abajo.
• Necesitas tener una API key activa para el entorno antes de configurar su URL. Si no existe, el dashboard te lo indica con un mensaje claro y un código 422.

Importante: solo se envían los webhooks generados a partir del momento en que la URL está configurada y activa. Eventos previos no se reenvían retroactivamente.

Verificación de autenticidad (firma HMAC)

Todos los webhooks live van firmados con HMAC-SHA256 usando el mismo client_secret que se te muestra al crear (o rotar) la API key del entorno. Llegan estas dos cabeceras adicionales:

Ejemplo de verificación en PHP:

$timestamp = $_SERVER['HTTP_X_AVIRATO_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_AVIRATO_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

if (!preg_match('/^t=(\d+),v1=([a-f0-9]+)$/', $signature, $m)) {
    http_response_code(400);
    exit;
}

$expected = hash_hmac('sha256', $timestamp . '.' . $body, $clientSecret);
if (!hash_equals($expected, $m[2])) {
    http_response_code(401);
    exit;
}

En Test, si tienes API key test creada, los webhooks de prueba se firman también con su secret. Si no, se envían sin firma para que puedas explorar el formato sin obligación de crear API key test todavía.

Política de reintentos

Cómo funciona en una línea

Cada vez que Avirato Payments te envia un webhook y tu endpoint no responde con HTTP 200, lo reintenta mas tarde. La espera entre cada fallo y el siguiente reintento crece: empieza en 10 minutos y termina en 48 horas. Tras un total de 10 intentos sin éxito Avirato Payments deja de reintentarlo automáticamente.

Cronograma completo

La tabla muestra, para un webhook que falla en cada intento, el momento exacto en el que tu endpoint recibe la siguiente llamada, contado desde que se produjo el evento original (autorización, refund, etc.).

En total son 10 intentos (un envío inicial + 9 reintentos) repartidos en una ventana de unos 4 días. El reloj no se reinicia en cada intento: cuanto más tarde respondes correctamente, más se habrán espaciado los siguientes reintentos.

Cómo saber en qué intento vamos

En el dashboard, en Integraciones > Actividad > Webhooks enviados (entorno Live), cada fila del historial muestra:

• Intentos: número de intentos consumidos hasta ahora (1 a 10).
• Último intento: la fecha y hora del último envío.
• HTTP: el código HTTP que devolvió tu endpoint en ese último envío.
• Estado: Entregado (success), Pendiente (todavía con reintentos por delante).

Si el endpoint sigue cayendo tras los 10 intentos

Si tras los 10 intentos (≈ 4 días) tu endpoint no ha respondido correctamente ni una sola vez, Avirato Payments deja de reintentarlo automáticamente aunque más tarde repares tu sistema. En ese caso:

1. Reactiva tu endpoint y verifica que ya responde correctamente con webhooks normales.
2. Para los eventos que quedaron pendientes, abre Integraciones > Actividad > Webhooks enviados, identifica los webhooks con estado Pendiente y fuerza el reenvío manual con el botón Reenviar. Cada reenvío manual hace una llamada HTTP nueva a tu endpoint con el mismo payload.

Si desactivas o eliminas tu URL de webhooks: los eventos siguen encolándose en Avirato Payments. El cron sigue contando reintentos para cada uno, así que si reactivas la URL dentro de la ventana de ≈ 4 días los pendientes se entregarán automáticamente en el siguiente tick (siempre que aún queden intentos disponibles para ese webhook). Pasada esa ventana los eventos quedan abandonados y no se vuelven a enviar.

Comportamiento del reenvio manual

• Si reenvias manualmente un webhook que estaba pendiente de reintentos y el reenvio tiene exito, los reintentos automaticos se detienen — el webhook ya se considera entregado.
• Puedes reenviar un webhook que ya fue entregado correctamente. El dashboard te pedira confirmacion antes para evitar duplicados accidentales, pero el reenvio se ejecuta igualmente si lo confirmas.

Fuente de verdad del estado del pago (Live)

En el entorno Live, las notificaciones del procesador tienen la ultima palabra sobre el estado real del pago. Esto significa que un pago puede cambiar de estado despues de que tu sistema lo haya tratado como completado.

Casos tipicos en los que puede llegar un webhook posterior que revierte un exito previo:

• Chargeback: el titular reclama el cargo a su banco
• Fraude detectado a posteriori: el procesador identifica una transaccion fraudulenta dias despues
• Reversion bancaria: el banco emisor revierte la operacion
• Correccion del procesador: una notificacion previa contenia datos incompletos o incorrectos

Cuando recibimos uno de estos eventos en Live, actualizamos el estado del pago en nuestro sistema (por ejemplo, de AUTHORISED a FAILED) y te enviamos el webhook correspondiente. Tu integracion debe:

• Aceptar webhooks asincronos que cambien el resultado de un pago previamente exitoso
• Tratar los webhooks (no la respuesta inmediata ni el redirect) como la referencia para la conciliacion y el estado final
• Volver a consultar la API (GET /payment/session/{sessionId}) cuando necesites el ultimo estado conocido

Test vs Live: en Test los webhooks los genera nuestro propio simulador y reflejan unicamente la simulacion que has lanzado. No hay chargebacks ni reverts en Test.

Formato general

Todos los webhooks llegan como POST a tu URL con este formato:

Cabeceras

Body

{
  "event_code": "AUTHORISATION",
  "data": {
    ...campos especificos del evento...
  }
}

Respuesta esperada

Tu endpoint debe responder con HTTP 200 y un body JSON:

{
  "status": "success"
}

Si tu endpoint no responde correctamente, el webhook se reintentara automaticamente con backoff exponencial.

Tipos de evento

AUTHORISATION — Pago completado (online o POS)

Se envia cuando un pago (online o POS) se autoriza correctamente o falla.

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 15000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "paymentStatus": "AUTHORISED",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "paymentSource": "external_api"
  }
}

Como identificar el tipo de pago por la referencia:

Ejemplo de pago POS exitoso:

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 8500,
    "currency": "EUR",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "paymentStatus": "AUTHORISED",
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628",
    "paymentSource": "external_api"
  }
}

Ejemplo de pago fallido (rechazado):

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 15000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "paymentStatus": "FAILED",
    "description": "Pedido #12345",
    "failedReason": "Refused",
    "paymentSource": "external_api"
  }
}

Importante: Los webhooks se envian tanto para pagos exitosos como fallidos. Comprueba siempre el campo paymentStatus para determinar el resultado.

REFUND — Reembolso procesado

Se envia cuando un reembolso se completa (exito o fallo) por el procesador.

{
  "event_code": "REFUND",
  "data": {
    "amount": 5000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "refundReason": "CUSTOMER REQUEST",
    "refundReference": "SHOP01-RFX-17195234567890",
    "status": "success",
    "customReference": "ORD-2026-12345",
    "paymentSource": "external_api"
  }
}

Ejemplo de reembolso fallido:

{
  "event_code": "REFUND",
  "data": {
    "amount": 5000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "refundReason": "CUSTOMER REQUEST",
    "refundReference": "SHOP01-RFX-17195234567890",
    "status": "failed",
    "failedReason": "Insufficient balance"
  }
}

PREAUTHORISATION — Resultado de captura, cancelacion o extension

Se envia cuando una operacion sobre una preautorizacion se completa. El campo action indica el tipo de operacion.

Captura completada

{
  "event_code": "PREAUTHORISATION",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "action": "capture",
    "result": "success",
    "amount": 45000,
    "currency": "EUR",
    "customReference": "ORD-2026-67890",
    "paymentSource": "external_api"
  }
}

Cancelacion completada

{
  "event_code": "PREAUTHORISATION",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "action": "cancellation",
    "result": "success",
    "customReference": "ORD-2026-67890",
    "paymentSource": "external_api"
  }
}

Extension completada

{
  "event_code": "PREAUTHORISATION",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "action": "extend",
    "result": "success",
    "expirationDate": "2026-08-15T00:00:00Z",
    "customReference": "ORD-2026-67890",
    "paymentSource": "external_api"
  }
}

Ejemplo de captura fallida (importe excede el autorizado):

{
  "event_code": "PREAUTHORISATION",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "action": "capture",
    "result": "failure",
    "failedReason": "Payment already captured, cannot capture again"
  }
}

CHARGEBACK — Contracargo

Se envia cuando un titular de tarjeta inicia un contracargo contra un pago. Los contracargos son procesados por el emisor de la tarjeta y pueden tardar dias o semanas en resolverse.

{
  "event_code": "CHARGEBACK",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "chargebackReference": "SHOP01-CHB-17195123456789",
    "action": "chargeback",
    "result": "success",
    "amount": 15000,
    "currency": "EUR",
    "reason": "Fraudulent transaction",
    "chargebackReasonCode": "10.4",
    "chargebackSchemeCode": "VISA_10_4",
    "defensePeriodEndsAt": "2026-06-15",
    "defendable": true,
    "disputeStatus": "Undefended",
    "paymentSource": "external_api"
  }
}

NOTIFICATION_OF_CHARGEBACK — Aviso previo de contracargo

Aviso anticipado de que un contracargo puede estar en camino. No todos los procesadores lo envian. Te permite prepararte antes de que el contracargo formal se procese.

{
  "event_code": "NOTIFICATION_OF_CHARGEBACK",
  "data": {
    "paymentReference": "SHOP01-PXT-17195123456789",
    "chargebackReference": "SHOP01-CHB-17195123456789",
    "action": "notification_of_chargeback",
    "result": "success",
    "amount": 15000,
    "currency": "EUR",
    "reason": "Cardholder disputes transaction",
    "chargebackReasonCode": "10.4",
    "chargebackSchemeCode": "VISA_10_4",
    "defensePeriodEndsAt": "2026-06-15",
    "defendable": true,
    "disputeStatus": "Undefended",
    "autoDefended": false,
    "arn": "74027600000012345678901",
    "paymentSource": "external_api"
  }
}

Contiene los mismos campos que CHARGEBACK mas dos campos adicionales opcionales:

Pagos recurrentes

Los pagos recurrentes (recurso subscription en la API) envian sus propios eventos. Todos comparten estos campos en data:

• Los de Test solo van a tu URL Test y llevan environment: "test".
• En Live recibes tambien los eventos de los pagos recurrentes creados desde el panel para tu webcode, no solo los creados por API.
• Usa subscriptionId + event_code + paymentReference (si viene) como clave de deduplicacion.

SUBSCRIPTION_CREATED — Primer pago correcto

El cliente ha pagado el primer importe y se ha guardado su tarjeta. El pago recurrente queda activo.

{
  "event_code": "SUBSCRIPTION_CREATED",
  "data": {
    "subscriptionId": "SHOP01-SB-3f9a1c2e",
    "status": "active",
    "planCode": "GOLD",
    "paymentReference": "SHOP01-PYS-1792069000123",
    "pspReference": "T7KQ2N9X4M8P6R3Z",
    "amount": 990,
    "currency": "EUR"
  }
}

SUBSCRIPTION_RENEWED — Cobro periodico correcto

{
  "event_code": "SUBSCRIPTION_RENEWED",
  "data": {
    "subscriptionId": "SHOP01-SB-3f9a1c2e",
    "status": "active",
    "planCode": "GOLD",
    "paymentReference": "SHOP01-PYSS-1794912000567-1",
    "pspReference": "T8LR3P0Y5N9Q7S4A",
    "amount": 2990,
    "currency": "EUR",
    "paymentsCount": 2,
    "lastChargeDate": "2026-11-05 06:00:12",
    "nextChargeDate": "2026-12-05 06:00:00"
  }
}

SUBSCRIPTION_FAILED — Cobro rechazado

Se envia cuando falla el primer pago (el pago recurrente queda en error) o un cobro periodico que todavia tiene reintentos (sigue active). En este segundo caso incluye retryCount, maxRetries y nextRetryAt.

{
  "event_code": "SUBSCRIPTION_FAILED",
  "data": {
    "subscriptionId": "SHOP01-SB-3f9a1c2e",
    "status": "active",
    "planCode": "GOLD",
    "paymentReference": "SHOP01-PYSS-1794912000567-1",
    "amount": 2990,
    "currency": "EUR",
    "error": "Not enough balance",
    "errorCode": "NOT_ENOUGH_BALANCE",
    "retryCount": 1,
    "maxRetries": 3,
    "nextRetryAt": "2026-11-05 11:00:12"
  }
}

SUBSCRIPTION_ERROR — Reintentos agotados (pausado)

El ultimo reintento tambien ha fallado. El pago recurrente pasa a paused con statusReason: payment_failed_max_retries y no se cobra mas hasta que lo reactives (con la tarjeta actual o pidiendo una nueva con update-card). En este caso no llega SUBSCRIPTION_FAILED.

{
  "event_code": "SUBSCRIPTION_ERROR",
  "data": {
    "subscriptionId": "SHOP01-SB-3f9a1c2e",
    "status": "paused",
    "planCode": "GOLD",
    "statusReason": "payment_failed_max_retries",
    "requiresAction": "reactivate",
    "lastError": "Expired card",
    "lastErrorCode": "CARD_EXPIRED"
  }
}

Pausa, reactivacion, cancelacion y cambio de tarjeta

{
  "event_code": "SUBSCRIPTION_CANCELLED",
  "data": {
    "subscriptionId": "SHOP01-SB-3f9a1c2e",
    "status": "cancelled",
    "planCode": "GOLD",
    "cancelledAt": "2026-12-20 10:15:03"
  }
}

Ejemplo en Test (mismo formato + environment):

{
  "event_code": "SUBSCRIPTION_REACTIVATED",
  "data": {
    "subscriptionId": "SHOP01-SB-a07c55d1",
    "status": "active",
    "planCode": null,
    "reactivatedAt": "2026-10-16 09:30:00",
    "nextChargeDate": "2026-10-16 09:30:00",
    "environment": "test"
  }
}

Webhooks en entorno Test

En el entorno Test, los webhooks no provienen del procesador de pagos real. Son generados automaticamente por el backend de Avirato Payments inmediatamente despues de completar la operacion simulada.

Diferencias con Live

Lo que debes saber

• El formato es exactamente el mismo: Puedes desarrollar tu logica de procesamiento de webhooks en Test y funcionara en Live sin cambios
• Llegan para pagos exitosos Y fallidos: Tanto en Live como en Test, recibiras webhooks cuando un pago se rechaza o una operacion falla
• URLs independientes por entorno: Los webhooks de Test se envian a la URL configurada para el entorno Test, y los de Live a la URL de Live. Configura ambas desde el panel de webhooks del dashboard
• Las referencias usan sufijos Test: Las paymentReference y operationReference contendran los infijos de test (-PXTT-, -RFXT-, etc.)
• Criterio de exito simple: Tanto en Live como en Test, basta con que tu endpoint responda HTTP 200 para que el webhook se marque como Entregado. Cualquier otro codigo de estado se considera fallo y activara los reintentos (en Live) o quedara como Fallido en el dashboard (en Test).
• Reenvio manual en Test y Live: Desde el panel de webhooks puedes reenviar manualmente cualquier fila. Tanto en Test como en Live, el reenvio utiliza la URL actualmente configurada para ese entorno, no la URL que se uso en el envio original. Si reenvias un webhook que ya aparece como Entregado, el dashboard te pedira confirmacion antes para evitar duplicados accidentales.

Ejemplo de webhook de test (pago online exitoso)

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 15000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195000005678",
    "paymentStatus": "AUTHORISED",
    "description": "Pedido test #12345",
    "customReference": "TEST-ORD-12345",
    "paymentSource": "external_api"
  }
}

Ejemplo de webhook de test (POS rechazado)

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 10077,
    "currency": "EUR",
    "paymentReference": "SHOP01-POSXT-17195300001234",
    "paymentStatus": "FAILED",
    "description": "Venta test #100",
    "failedReason": "Refused",
    "paymentSource": "external_api"
  }
}

Referencia rapida

Buenas practicas

Idempotencia en tu endpoint

Tu endpoint de webhook puede recibir la misma notificacion mas de una vez (por reintentos o duplicados del procesador). Asegurate de que procesar el mismo webhook dos veces no cause problemas: usa paymentReference o refundReference como clave de deduplicacion.

Respuesta rapida

Responde al webhook lo antes posible (idealmente en menos de 5 segundos). Si necesitas hacer procesamiento pesado, encola el trabajo y responde inmediatamente con HTTP 200.

No dependas de un solo canal

Usa los webhooks como canal principal, pero implementa tambien:

1. Verificacion post-redirect: Cuando el cliente vuelva a urlOk, consulta GET /payment/session/{id} para confirmar
2. Polling de seguridad: Un proceso periodico que consulte sesiones en estado pending antiguas para detectar pagos completados que no hayas procesado

Manejo de errores

Formato de error estandar

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": {
    "message": "Descripcion legible del error",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

Nota de seguridad: Los errores internos del servidor (5xx) devuelven un mensaje generico ("An error has occurred...") para no exponer detalles de implementacion. El traceId permite al equipo de soporte investigar el error concreto.

Nota sobre entornos: Los codigos de error, formatos y mensajes son identicos en los entornos Live y Test. No hay diferencias en el manejo de errores entre entornos.

Catalogo de codigos de error

Errores de autenticacion y autorizacion (11xxx)

Errores de validacion (12xxx)

Errores de recurso (10xxx)

Errores de POS (13xxx)

Conflictos de idempotencia (409)

Estos conflictos no llevan un codigo numerico interno: el mensaje permite distinguirlos del 409 de POS ocupado (codigo 13005).

Errores internos (99xxx)

Pagos recurrentes

Mensajes propios de /subscriptions (mismo formato de error). Usa el message y el HTTP para decidir; el code es el generico de validacion o de recurso.

Recurso no encontrado (404)

Accion no permitida en el estado actual (400)

Validacion (400)

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "message": "External device is busy.",
    "code": 13005,
    "statusCode": 409,
    "traceId": "b2f3d36dc305249e8d1ebaa49ef616f1"
  }
}

Buenas practicas

Reintentos

• Errores 4xx: No reintentes (el problema esta en la peticion)
• Errores 5xx: Reintenta con backoff exponencial (1s, 2s, 4s, 8s...)
• 409: si es 13005 (terminal ocupado), espera 5-10 segundos y reintenta. Si el mensaje empieza por Idempotency key…, no reintentes a ciegas: corrige la clave o el body de la peticion
• Siempre usa Idempotency-Key para que los reintentos sean seguros

Logging

Registra el traceId de las respuestas de error para facilitar la comunicacion con soporte tecnico.

Validacion previa

Valida los datos antes de enviar la peticion para evitar errores 400:

• amount.value debe ser un entero positivo (centimos)
• amount.currency debe ser exactamente 3 letras mayusculas (EUR, GBP o USD)
• webcode no puede estar vacio
• URLs (urlOk, urlKo) deben ser URLs validas con protocolo
• reason en reembolsos debe ser uno de los 5 valores exactos permitidos
• Pagos recurrentes: intervalUnit en day, week, month, year; intervalCount >= 1; billingDay (1-31) solo con month; endAt futura; returnUrl http/https

Ejemplos Completos

Ejemplos de flujos de integracion end-to-end con cURL. Sustituye la API key y el webcode por los tuyos.

Flujo 1: Pago online completo (Live)

Ver explicacion completa del flujo

1.1 Crear sesion de pago

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 25000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false
  }'

Respuesta (201 Created):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "paymentUrl": "https://aviratopayments.com/pay-external/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 25000, "currency": "EUR" },
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "createdAt": "2026-06-28 10:30:00"
  }
}

1.2 Redirigir al cliente

Redirige al cliente a la paymentUrl devuelta. El cliente vera la pagina de pago segura y completara la transaccion. Tras pagar sera redirigido a urlOk (exito) o urlKo (fallo/cancelacion).

1.3 Consultar estado del pago

Una vez el cliente ha sido redirigido de vuelta, consulta la sesion para obtener el resultado y el paymentReference:

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "status": "completed",
    "amount": { "value": 25000, "currency": "EUR" },
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "createdAt": "2026-06-28 10:30:00",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "completedAt": "2026-06-28 10:35:22",
    "paymentStatus": "AUTHORISED",
    "attempts": [
      {
        "paymentReference": "SHOP01-PXT-17195000005678",
        "status": "authorised",
        "createdAt": "2026-06-28 10:34:00"
      }
    ]
  }
}

El paymentReference (SHOP01-PXT-17195000005678) es el que usaras para cualquier modificacion posterior.

Flujo 2: Preautorizacion + captura (o cancelacion)

Ver explicacion completa del flujo

2.1 Crear preautorizacion

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preauth-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 50000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Deposito garantia - Servicio #67890",
    "customReference": "ORD-2026-67890",
    "isPreAuth": true
  }'

El cliente completa la preautorizacion. Obten el paymentReference consultando la sesion como en el Flujo 1.

2.2 Capturar el importe final (parcial)

Cuando el servicio se completa, captura el importe real (que puede ser menor al preautorizado):

curl -X POST https://aviratopayments.com/external/v1/payment/capture \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capture-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "amount": {
      "value": 45000,
      "currency": "EUR"
    }
  }'

Respuesta (202 Accepted):

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195100001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "amount": { "value": 45000, "currency": "EUR" },
    "status": "received",
    "createdAt": "2026-06-29 11:00:00"
  }
}

2.3 (Alternativa) Cancelar la preautorizacion

Si el servicio se cancela, libera los fondos:

curl -X POST https://aviratopayments.com/external/v1/payment/cancel \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195000009876"
  }'

Respuesta (202 Accepted):

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195200001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "status": "received",
    "createdAt": "2026-06-29 12:00:00"
  }
}

Flujo 3: Pago POS + reembolso (Live)

Ver explicacion completa del flujo

3.1 Listar terminales disponibles

curl -X GET "https://aviratopayments.com/external/v1/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200 OK):

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-123456789",
      "status": "boarded",
      "name": "Mostrador Principal",
      "model": "V400m",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-20T08:30:00Z"
    }
  ]
}

3.2 Enviar pago al terminal

curl -X POST https://aviratopayments.com/external/v1/pos/payment \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-sale-11111" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-123456789",
    "amount": {
      "value": 8500,
      "currency": "EUR"
    },
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628"
  }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSX-17195300001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "poiId": "V400m-123456789",
    "amount": { "value": 8500, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "KVGQSN3K2SKFNVNS",
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628",
    "createdAt": "2026-06-28 14:15:00"
  }
}

3.3 Reembolso parcial del pago POS

El paymentReference del pago POS es el posPaymentId:

curl -X POST https://aviratopayments.com/external/v1/payment/refund \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-pos-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": {
      "value": 2000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Respuesta (202 Accepted):

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195400001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": { "value": 2000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 15:00:00"
  }
}

Flujo 4: Listar pagos con paginacion

Ver explicacion completa del flujo

4.1 Primera pagina

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta:

{
  "success": true,
  "data": {
    "payments": [
      {
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "completed",
        "amount": { "value": 25000, "currency": "EUR" },
        "description": "Pedido #12345",
        "customReference": "ORD-2026-12345",
        "isPreAuth": false,
        "createdAt": "2026-06-28 10:30:00",
        "completedAt": "2026-06-28 10:35:22",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "paymentStatus": "AUTHORISED"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NX0=",
      "hasMore": true,
      "total": 23
    }
  }
}

4.2 Pagina siguiente

Usa el cursor de la respuesta anterior:

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5&cursor=eyJpZCI6NX0=" \
  -H "X-API-KEY: tu_api_key_live"

Repite hasta que meta.hasMore sea false.

Flujo 5: Verificar modificaciones

Ver explicacion completa del flujo

5.1 Listar modificaciones de una sesion online

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

5.2 Listar modificaciones de un pago POS

curl -X GET "https://aviratopayments.com/external/v1/pos/payment/SHOP01-POSX-17195300001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

5.3 Listar todas las modificaciones con filtros

curl -X GET "https://aviratopayments.com/external/v1/modifications?webcode=SHOP01&type=refund&status=success&take=10" \
  -H "X-API-KEY: tu_api_key_live"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195400001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-POSX-17195300001234",
        "sessionId": "SHOP01-POSX-17195300001234",
        "status": "success",
        "requestedAt": "2026-06-28 15:00:00",
        "createdAt": "2026-06-28 15:00:00",
        "resolvedAt": "2026-06-28 15:00:05",
        "amount": { "value": 2000, "currency": "EUR" },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": null,
      "hasMore": false,
      "total": 1
    }
  }
}

Flujo 6: Pago online completo en entorno TEST

Ver explicacion completa del flujo

Este flujo demuestra como probar la integracion sin dinero real.

6.1 Crear sesion de pago (Test)

curl -X POST https://aviratopayments.com/external/v1/test/payment/session \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-99999" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 10000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999"
  }'

Respuesta (201 Created):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXTT-17195500001234",
    "paymentUrl": "https://aviratopayments.com/pay-external-test/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 10000, "currency": "EUR" },
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "isPreAuth": false,
    "createdAt": "2026-06-28 16:00:00"
  }
}

Nota que el sessionId tiene el infijo -EXTT- y la paymentUrl apunta a /pay-external-test/.

6.2 Simular el pago

Redirige al cliente a la paymentUrl. Vera un formulario de pago simulado. Para un pago exitoso, introduce:

• Numero: 4111 1111 1111 1111
• Expiracion: 12/30
• CVC: 737
• Nombre: Test User (cualquier nombre que no sea un valor especial)

Para simular un rechazo, usa como nombre del titular: DECLINED

6.3 Recibir webhook simulado

Inmediatamente despues de completar el pago, recibiras un webhook en tu URL configurada:

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 10000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "paymentStatus": "AUTHORISED",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

6.4 Consultar estado (Test)

curl -X GET "https://aviratopayments.com/external/v1/test/payment/session/SHOP01-EXTT-17195500001234?webcode=SHOP01" \
  -H "X-API-KEY: <tu_api_key_test>"

La respuesta tendra status: "completed" con el paymentReference del entorno test.

Flujo 7: Pago POS en entorno TEST

Ver explicacion completa del flujo

7.1 Listar terminales simulados

curl -X GET "https://aviratopayments.com/external/v1/test/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: <tu_api_key_test>"

Respuesta (200 OK):

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-TEST-000001",
      "status": "boarded",
      "name": "Terminal Test 1 - Mostrador",
      "model": "V400m",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "S1F2-TEST-000002",
      "status": "boarded",
      "name": "Terminal Test 2 - Terraza",
      "model": "S1F2",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "P400Plus-TEST-000003",
      "status": "boarded",
      "name": "Terminal Test 3 - Almacen",
      "model": "P400Plus",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Con syncFromProvider=true solo se devuelven los 2 online (V400m-TEST-000001 y S1F2-TEST-000002).

7.2 Pago exitoso (importe no termina en 77, 99 ni 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-001" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001"
  }'

Respuesta (200 OK) - Exito (los ultimos 2 digitos de 5000 son 00):

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600001234",
    "paymentReference": "SHOP01-POSXT-17195600001234",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 5000, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "test_psp_a1b2c3d4e5f67890",
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001",
    "createdAt": "2026-06-28 17:00:00"
  }
}

7.3 Pago rechazado (importe termina en 77)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-002" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 10077,
      "currency": "EUR"
    },
    "description": "Test POS - Rechazo simulado"
  }'

Respuesta (200 OK) - Rechazado:

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600005678",
    "paymentReference": "SHOP01-POSXT-17195600005678",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 10077, "currency": "EUR" },
    "status": "failed",
    "isPreAuth": false,
    "pspReference": "test_psp_f8e7d6c5b4a39012",
    "errorMessage": "Card declined (test simulation)",
    "description": "Test POS - Rechazo simulado",
    "createdAt": "2026-06-28 17:05:00"
  }
}

7.4 Timeout simulado (importe termina en 99)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-003" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 2599,
      "currency": "EUR"
    },
    "description": "Test POS - Timeout simulado"
  }'

Respuesta (200 OK) - Timeout:

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600009012",
    "paymentReference": "SHOP01-POSXT-17195600009012",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 2599, "currency": "EUR" },
    "status": "timeout",
    "isPreAuth": false,
    "errorMessage": "POS payment timeout. The payment may still be processed asynchronously via webhook.",
    "description": "Test POS - Timeout simulado",
    "createdAt": "2026-06-28 17:10:00"
  }
}

7.5 Terminal offline (error 502)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-004" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "P400Plus-TEST-000003",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal offline"
  }'

Respuesta (502) - Error de terminal:

{
  "success": false,
  "error": {
    "message": "Error in POS payment response: Reject",
    "code": 13004,
    "statusCode": 502,
    "traceId": "abc123def456..."
  }
}

7.6 Terminal ocupado (importe termina en 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-005" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 1055,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal ocupado"
  }'

Respuesta (409) - Terminal ocupado:

{
  "success": false,
  "error": {
    "message": "Terminal busy (test simulation)",
    "code": 13005,
    "statusCode": 409,
    "traceId": "abc123def456..."
  }
}

7.7 poiId no valido (error 400)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "TERMINAL-INVENTADO-123",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    }
  }'

Respuesta (400) - Terminal no valido:

{
  "success": false,
  "error": {
    "message": "The specified terminal is not valid: device not found",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

Flujo 8: Modificacion en entorno TEST + webhook

Ver explicacion completa del flujo

8.1 Reembolso en Test

curl -X POST https://aviratopayments.com/external/v1/test/payment/refund \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-refund-001" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": {
      "value": 3000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Respuesta (202 Accepted):

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFXT-17195700001234",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": { "value": 3000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 18:00:00"
  }
}

8.2 Webhook simulado que recibiras

Inmediatamente (< 1 segundo) recibiras en tu URL de webhook:

{
  "event_code": "REFUND",
  "data": {
    "amount": 3000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "refundReason": "CUSTOMER REQUEST",
    "refundReference": "SHOP01-RFXT-17195700001234",
    "status": "success",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

En Test, los webhooks de modificaciones se generan y envian automaticamente tras la peticion, sin necesidad de esperar al procesador.

9. Pago recurrente completo (Test)

Alta mensual de 29,90 EUR, renovacion, cobro fallido con reintentos, pausa y cambio de tarjeta. Todo con la key Test y sin abrir ninguna pagina gracias a los simuladores.

9.1 Crear el pago recurrente

curl -X POST https://aviratopayments.com/external/v1/test/subscriptions \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sb-cli42-gold-001" \
  -d '{
    "webcode": "SHOP01",
    "amount": { "value": 2990, "currency": "EUR" },
    "intervalUnit": "month",
    "intervalCount": 1,
    "returnUrl": "https://tu-web.com/pago-recurrente/ok",
    "planCode": "GOLD",
    "customerInternalId": "CLI-42"
  }'

Respuesta 201 con linkId (SHOP01-LK-...) y paymentUrl. En Live rediriges al cliente a paymentUrl; en Test puedes abrirla o simular el pago:

9.2 Simular el primer pago

curl -X POST https://aviratopayments.com/external/v1/test/subscriptions/links/SHOP01-LK-1792068995050/simulate-checkout \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -d '{ "webcode": "SHOP01", "result": "success" }'

Recibes en tu URL Test:

{
  "event_code": "SUBSCRIPTION_CREATED",
  "data": {
    "subscriptionId": "SHOP01-SB-a07c55d1",
    "status": "active",
    "planCode": "GOLD",
    "paymentReference": "SHOP01-PYS-1792069000123",
    "pspReference": "TEST3F9A1C2E7B4D",
    "amount": 2990,
    "currency": "EUR",
    "environment": "test"
  }
}

Guarda subscriptionId: es la clave para todas las operaciones siguientes.

9.3 Forzar una renovacion

curl -X POST https://aviratopayments.com/external/v1/test/subscriptions/SHOP01-SB-a07c55d1/simulate-renewal \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -d '{ "webcode": "SHOP01", "result": "success" }'

Llega SUBSCRIPTION_RENEWED con paymentsCount y nextChargeDate del siguiente ciclo.

9.4 Cobro fallido, reintentos y pausa

Lanza simulate-renewal con "result": "card_expired" cuatro veces (cobro + 3 reintentos):

• Intentos 1 a 3: SUBSCRIPTION_FAILED con retryCount y nextRetryAt; sigue active.
• Intento 4: SUBSCRIPTION_ERROR con status: paused y statusReason: payment_failed_max_retries.

9.5 Pedir una tarjeta nueva

curl -X POST https://aviratopayments.com/external/v1/test/subscriptions/SHOP01-SB-a07c55d1/update-card \
  -H "X-API-KEY: <tu_api_key_test>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sb-a07c55d1-card-001" \
  -d '{ "webcode": "SHOP01", "returnUrl": "https://tu-web.com/tarjeta/ok" }'

Devuelve un paymentUrl y un nuevo linkId; el pago recurrente pasa a pendingNewCard. Envia el link a tu cliente (o usa simulate-checkout con ese linkId). Al pagar, vuelve a active y recibes SUBSCRIPTION_REACTIVATED (en Live, SUBSCRIPTION_CARD_UPDATED).

Si en lugar de cambiar la tarjeta quieres reintentar con la actual, usa POST /subscriptions/{id}/reactivate. Un pago recurrente cancelado no admite ninguna de las dos acciones.

9.6 Consultar el historial

curl "https://aviratopayments.com/external/v1/test/subscriptions/SHOP01-SB-a07c55d1/payments?webcode=SHOP01" \
  -H "X-API-KEY: <tu_api_key_test>"

Cada cobro aparece con su resultado y, si fallo, su refusalReason (p. ej. Expired card).