External API

Documentación para desarrolladores

Integra pagos online y POS, consulta operaciones y recibe webhooks con la API externa de Avirato Payments.

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)

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)

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)

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

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

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

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

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

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.