Queries

Obtain payment detail

Returns complete information for an online payment session, including all payment attempts and, if the session is completed, the authorized payment reference (paymentReference).

This endpoint is the main way to obtain the paymentReference you need to perform modifications (refunds, captures, 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}

Parameters

Parameter	Location	Type	Required	Description
`sessionId`	Path	string	Yes	The `sessionId` returned when creating the session
`webcode`	Query	string	Yes	Your business identifier

Example

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234?webcode=SHOP01" \
  -H "X-API-KEY: your_live_api_key"

Response (200) - Completed session

{
  "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"
      }
    ]
  }
}

Response (200) - Pending session

When the session has not yet completed, it does not include paymentReference, completedAt, or 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": []
  }
}

Response fields

Field	Always present	Description
`sessionId`	Yes	Unique session identifier
`status`	Yes	Session status: `pending`, `completed`, `failed`, `expired`, `cancelled`
`amount`	Yes	Amount and currency requested when creating the session
`countryCode`	Yes	Configured country
`shopperLocale`	Yes	Configured language
`deliverAt`	Yes	Delivery date (may be `null`)
`description`	Yes	Description (may be `null`)
`customReference`	Yes	Your internal reference (may be `null`)
`isPreAuth`	Yes	Whether it was created as pre-authorization
`urlOk` / `urlKo`	Yes	Configured return URLs
`createdAt`	Yes	Session creation date and time
`paymentReference`	Only if `completed`	Authorized payment reference. Use this for modifications
`completedAt`	Only if `completed`	Date when payment was authorized
`paymentStatus`	Only if `completed`	Payment status at the processor (e.g. `AUTHORISED`). In Live this value can change over time if the processor notifies later events (chargeback, fraud, reversal). Check webhooks or call this endpoint again if you need the latest status.
`attempts`	Yes	Informational array with registered payment attempts. May be empty

Errors

Code	HTTP	Cause
12001	400	Missing `webcode` parameter
10404	404	Session not found
11008	403	Session does not belong to your webcode or environment

---

List payments

Lists all online payment sessions with filters and cursor-based pagination.

Live: GET https://aviratopayments.com/external/v1/payment/sessions?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/payment/sessions?webcode={webcode}

Query parameters

Parameter	Type	Required	Description
`webcode`	string	Yes	Your business identifier
`status`	string	No	Filter by status: `pending`, `completed`, `failed`, `expired`, `cancelled`
`created_at_start`	string	No	Start date (filter)
`created_at_end`	string	No	End date (filter)
`cursor`	string	No	Pagination cursor (from previous response)
`take`	integer	No	Results per page (1-100, default: 20)
`order`	string	No	Result order: `asc` or `desc` (default: `asc`)

Example

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=10" \
  -H "X-API-KEY: your_live_api_key"

Response (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
    }
  }
}

Fields for each session in the listing

Field	Description
`sessionId`	Session identifier
`status`	Current status
`amount`	Amount and currency
`description`	Description (may be `null`)
`customReference`	Your internal reference (may be `null`)
`isPreAuth`	Whether it is pre-authorization
`createdAt`	Creation date and time
`completedAt`	Completion date (may be `null`)
`paymentReference`	Authorized payment reference (may be `null` if not completed)
`paymentStatus`	Payment status: `AUTHORISED`, `FAILED`, `REFUNDED`, `PARTIALLYREFUNDED`, `CANCELED`, `ACTIVEDEPOSIT` (may be `null`). In Live the value can evolve after later webhooks (see Webhooks).

Cursor pagination

Pagination works with opaque cursors (not page numbers):

# First page
GET .../payment/sessions?webcode=SHOP01&take=20

# Next page (using cursor from meta.cursor)
GET .../payment/sessions?webcode=SHOP01&take=20&cursor=eyJpZCI6NDJ9

# Repeat until meta.hasMore == false

Cursors are opaque strings. Do not try to decode or build them manually; simply pass the value of meta.cursor as-is.

---

List modifications for a payment

Lists all modification operations (refund, capture, cancel, extend) associated with an online payment session.

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}

Parameters

Parameter	Location	Type	Required	Description
`sessionId`	Path	string	Yes	The payment session `sessionId`
`webcode`	Query	string	Yes	Your business identifier
`type`	Query	string	No	Filter by type: `refund`, `capture`, `cancel`, `extend`
`cursor`	Query	string	No	Pagination cursor
`take`	Query	integer	No	Results per page (1-100, default: 20)
`order`	Query	string	No	Order: `asc` or `desc` (default: `asc`)

Example

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: your_live_api_key"

Response (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
    }
  }
}

Fields for each modification

Field	Always present	Description
`operationReference`	Yes	Unique operation reference
`operationType`	Yes	Type: `refund`, `capture`, `cancel`, `extend`
`paymentReference`	Yes	Original payment reference the operation was performed on
`sessionId`	Yes	Associated payment session
`status`	Yes	Status: `pending`, `success`, `failed`
`requestedAt`	Yes	When the operation was requested
`createdAt`	Yes	Record creation date and time
`resolvedAt`	Yes	When it completed (or failed). `null` if pending
`amount`	Only refund and capture	Operation amount
`reason`	Only refund	Refund reason

---

List POS payment modifications

Lists all modification operations associated with a specific POS payment.

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}

Parameters

Parameter	Location	Type	Required	Description
`posPaymentId`	Path	string	Yes	The POS payment `posPaymentId`
`webcode`	Query	string	Yes	Your business identifier
`type`	Query	string	No	Filter by type: `refund`, `capture`, `cancel`, `extend`
`cursor`	Query	string	No	Pagination cursor
`take`	Query	integer	No	Results per page (1-100, default: 20)
`order`	Query	string	No	Order: `asc` or `desc` (default: `asc`)

Example

curl -X GET "https://aviratopayments.com/external/v1/pos/payment/SHOP01-POSX-17195300001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: your_live_api_key"

Response (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
    }
  }
}

Response fields are identical to List modifications for a payment.

Errors

Code	HTTP	Cause
12001	400	Missing `webcode` parameter
10404	404	POS payment not found
11008	403	POS payment does not belong to your webcode or environment

---

List all modifications

Lists all modification operations for your business, regardless of which payment they belong to. Allows filtering by type, status, date, and free text.

Live: GET https://aviratopayments.com/external/v1/modifications?webcode={webcode}
Test: GET https://aviratopayments.com/external/v1/test/modifications?webcode={webcode}

Query parameters

Parameter	Type	Required	Description
`webcode`	string	Yes	Your business identifier
`type`	string	No	Filter by type: `refund`, `capture`, `cancel`, `extend`
`status`	string	No	Filter by status: `pending`, `success`, `failed`
`dateFrom`	string	No	Start date (format `YYYY-MM-DD`)
`dateTo`	string	No	End date (format `YYYY-MM-DD`)
`search`	string	No	Free-text search (references, reasons, etc.)
`cursor`	string	No	Pagination cursor
`take`	integer	No	Results per page (1-100, default: 20)
`order`	string	No	Order: `asc` or `desc` (default: `asc`)

Example

curl -X GET "https://aviratopayments.com/external/v1/modifications?webcode=SHOP01&type=refund&status=success&take=10" \
  -H "X-API-KEY: your_live_api_key"

Response (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
    }
  }
}

This endpoint returns modifications from all payments (online and POS). You can identify payment type by reference: -PXT- (online Live), -PXTT- (online Test), -POSX- (POS Live), -POSXT- (POS Test).

---

Pagination

All listing endpoints use cursor-based pagination. Cursors are opaque strings representing the current position in the result set.

How it works

First request: Call the endpoint without the cursor parameter. You will receive the first results and a meta.cursor
Next page: If meta.hasMore is true, use the value of meta.cursor as the cursor parameter on the next request
End: When meta.hasMore is false, there are no more results

`meta` fields

Field	Description
`cursor`	Cursor to get the next page. `null` if there are no more
`hasMore`	`true` if more results are available
`total`	Total number of records matching the filters

# Page 1
curl ".../payment/sessions?webcode=SHOP01&take=10"
# meta: { "cursor": "eyJpZCI6MTB9", "hasMore": true, "total": 45 }

# Page 2
curl ".../payment/sessions?webcode=SHOP01&take=10&cursor=eyJpZCI6MTB9"
# meta: { "cursor": "eyJpZCI6MjB9", "hasMore": true, "total": 45 }

# Page 3
curl ".../payment/sessions?webcode=SHOP01&take=10&cursor=eyJpZCI6MjB9"
# meta: { "cursor": null, "hasMore": false, "total": 45 }

Important: Cursors are opaque. Do not try to decode, modify, or build them manually. Simply pass the value exactly as you receive it.

Developer documentation

Queries

Obtain payment detail

Parameters

Example

Response (200) - Completed session

Response (200) - Pending session

Response fields

Errors

List payments

Query parameters

Example

Response (200)

Fields for each session in the listing

List modifications for a payment

Parameters

Example

Response (200)

Fields for each modification

List POS payment modifications

Parameters

Example

Response (200)

Errors

List all modifications

Query parameters

Example

Response (200)

How it works

`meta` fields

Navigation example

Developer documentation

Queries

Obtain payment detail

Parameters

Example

Response (200) - Completed session

Response (200) - Pending session

Response fields

Errors

List payments

Query parameters

Example

Response (200)

Fields for each session in the listing

Cursor pagination

List modifications for a payment

Parameters

Example

Response (200)

Fields for each modification

List POS payment modifications

Parameters

Example

Response (200)

Errors

List all modifications

Query parameters

Example

Response (200)

Pagination

How it works

meta fields

Navigation example

`meta` fields