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