Índice de la documentación

Primeros pasos

Cobros

Gestión de pagos

Notificaciones

Referencia

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

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

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

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

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

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

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

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

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

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

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

Respuesta (200 OK):

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

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

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

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

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

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

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

bash
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

bash
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

bash
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

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

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

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

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

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

bash
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

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

Respuesta (200 OK):

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

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

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

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

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

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

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

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

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

7.6 Terminal ocupado (importe termina en 55)

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

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

7.7 poiId no valido (error 400)

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

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

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

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

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

bash
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

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

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

bash
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

bash
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

bash
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).