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: | poiId | Nombre | Modelo | Conectividad | |-------|--------|--------|-------------| | V400m-TEST-000001 | Terminal Test 1 - Mostrador | V400m | Online | | S1F2-TEST-000002 | Terminal Test 2 - Terraza | S1F2 | Online | | P400Plus-TEST-000003 | Terminal Test 3 - Almacen | P400Plus | Offline | Con syncFromProvider=true, solo se devuelven los 2 terminales online. Con syncFromProvider=false, se devuelven los 3. El terminal offline (P400Plus-TEST-000003) permite probar el manejo del 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