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

Parametro	Ubicacion	Tipo	Requerido	Descripcion
`sessionId`	Path	string	Si	El `sessionId` devuelto al crear la sesion
`webcode`	Query	string	Si	Identificador de tu negocio

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

Campo	Siempre presente	Descripcion
`sessionId`	Si	Identificador unico de la sesion
`status`	Si	Estado de la sesion: `pending`, `completed`, `failed`, `expired`, `cancelled`
`amount`	Si	Importe y divisa solicitados al crear la sesion
`countryCode`	Si	Pais configurado
`shopperLocale`	Si	Idioma configurado
`deliverAt`	Si	Fecha de entrega (puede ser `null`)
`description`	Si	Descripcion (puede ser `null`)
`customReference`	Si	Tu referencia interna (puede ser `null`)
`isPreAuth`	Si	Si fue creada como preautorizacion
`urlOk` / `urlKo`	Si	URLs de retorno configuradas
`createdAt`	Si	Fecha y hora de creacion de la sesion
`paymentReference`	Solo si `completed`	Referencia del pago autorizado. Usa esta para modificaciones
`completedAt`	Solo si `completed`	Fecha en que se autorizo el pago
`paymentStatus`	Solo si `completed`	Estado del pago en el procesador (ej: `AUTHORISED`). En Live este valor puede cambiar con el tiempo si el procesador notifica eventos posteriores (chargeback, fraude, reversion). Consulta los webhooks o vuelve a llamar a este endpoint si necesitas el ultimo estado.
`attempts`	Si	Array informativo con los intentos de pago registrados. Puede estar vacio

Errores

Codigo	HTTP	Causa
12001	400	Falta parametro `webcode`
10404	404	Sesion no encontrada
11008	403	La sesion no pertenece a tu webcode o entorno

---

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

Parametro	Tipo	Requerido	Descripcion
`webcode`	string	Si	Identificador de tu negocio
`status`	string	No	Filtrar por estado: `pending`, `completed`, `failed`, `expired`, `cancelled`
`created_at_start`	string	No	Fecha de inicio (filtro)
`created_at_end`	string	No	Fecha de fin (filtro)
`cursor`	string	No	Cursor de paginacion (de la respuesta anterior)
`take`	integer	No	Resultados por pagina (1-100, por defecto: 20)
`order`	string	No	Orden de resultados: `asc` o `desc` (por defecto: `asc`)

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

Campo	Descripcion
`sessionId`	Identificador de la sesion
`status`	Estado actual
`amount`	Importe y divisa
`description`	Descripcion (puede ser `null`)
`customReference`	Tu referencia interna (puede ser `null`)
`isPreAuth`	Si es preautorizacion
`createdAt`	Fecha y hora de creacion
`completedAt`	Fecha de completado (puede ser `null`)
`paymentReference`	Referencia del pago autorizado (puede ser `null` si no esta completada)
`paymentStatus`	Estado del pago: `AUTHORISED`, `FAILED`, `REFUNDED`, `PARTIALLYREFUNDED`, `CANCELED`, `ACTIVEDEPOSIT` (puede ser `null`). En Live el valor puede evolucionar tras webhooks posteriores (ver Webhooks).

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

Parametro	Ubicacion	Tipo	Requerido	Descripcion
`sessionId`	Path	string	Si	El `sessionId` de la sesion de pago
`webcode`	Query	string	Si	Identificador de tu negocio
`type`	Query	string	No	Filtrar por tipo: `refund`, `capture`, `cancel`, `extend`
`cursor`	Query	string	No	Cursor de paginacion
`take`	Query	integer	No	Resultados por pagina (1-100, por defecto: 20)
`order`	Query	string	No	Orden: `asc` o `desc` (por defecto: `asc`)

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

Campo	Siempre presente	Descripcion
`operationReference`	Si	Referencia unica de la operacion
`operationType`	Si	Tipo: `refund`, `capture`, `cancel`, `extend`
`paymentReference`	Si	Referencia del pago original sobre el que se opero
`sessionId`	Si	Sesion de pago asociada
`status`	Si	Estado: `pending`, `success`, `failed`
`requestedAt`	Si	Cuando se solicito la operacion
`createdAt`	Si	Fecha y hora de creacion del registro
`resolvedAt`	Si	Cuando se completo (o fallo). `null` si esta pendiente
`amount`	Solo refund y capture	Importe de la operacion
`reason`	Solo refund	Motivo del reembolso

---

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

Parametro	Ubicacion	Tipo	Requerido	Descripcion
`posPaymentId`	Path	string	Si	El `posPaymentId` del pago POS
`webcode`	Query	string	Si	Identificador de tu negocio
`type`	Query	string	No	Filtrar por tipo: `refund`, `capture`, `cancel`, `extend`
`cursor`	Query	string	No	Cursor de paginacion
`take`	Query	integer	No	Resultados por pagina (1-100, por defecto: 20)
`order`	Query	string	No	Orden: `asc` o `desc` (por defecto: `asc`)

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

Codigo	HTTP	Causa
12001	400	Falta parametro `webcode`
10404	404	Pago POS no encontrado
11008	403	El pago POS no pertenece a tu webcode o entorno

---

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

Parametro	Tipo	Requerido	Descripcion
`webcode`	string	Si	Identificador de tu negocio
`type`	string	No	Filtrar por tipo: `refund`, `capture`, `cancel`, `extend`
`status`	string	No	Filtrar por estado: `pending`, `success`, `failed`
`dateFrom`	string	No	Fecha de inicio (formato `YYYY-MM-DD`)
`dateTo`	string	No	Fecha de fin (formato `YYYY-MM-DD`)
`search`	string	No	Busqueda por texto libre (en referencias, razones, etc.)
`cursor`	string	No	Cursor de paginacion
`take`	integer	No	Resultados por pagina (1-100, por defecto: 20)
`order`	string	No	Orden: `asc` o `desc` (por defecto: `asc`)

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

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

Campos de `meta`

Campo	Descripcion
`cursor`	Cursor para obtener la siguiente pagina. `null` si no hay mas
`hasMore`	`true` si hay mas resultados disponibles
`total`	Numero total de registros que coinciden con los filtros

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.

Documentación para desarrolladores

Consultas

Obtener detalle de un pago

Parametros

Ejemplo

Respuesta (200) - Sesion completada

Respuesta (200) - Sesion pendiente

Campos de respuesta

Errores

Listar pagos

Parametros de query

Ejemplo

Respuesta (200)

Campos de cada sesion en el listado

Paginacion con cursores

Listar modificaciones de un pago

Parametros

Ejemplo

Respuesta (200)

Campos de cada modificacion

Listar modificaciones de un pago POS

Parametros

Ejemplo

Respuesta (200)

Errores

Listar todas las modificaciones

Parametros de query

Ejemplo

Respuesta (200)

Paginacion

Como funciona

Campos de meta

Ejemplo de navegacion

Campos de `meta`