# Retrieve List of Payments with Filtering Options

**GET** `/v2/mia/payments`

This endpoint allows retrieving a list of payments, using filters and sorting options to narrow down the results. The returned data includes details for each payment, such as amount, commission, payment status, payer information, etc.

***

**Request parameters (query)**

| Name             | Type                | Required | Description                                                                          |
| ---------------- | ------------------- | -------- | ------------------------------------------------------------------------------------ |
| `count`          | `integer`           | Yes      | Number of items returned in the result                                               |
| `offset`         | `integer`           | Yes      | Starting index in the result set                                                     |
| `sortBy`         | `string (enum)`     | No       | Field to sort by: `orderId`, `amount`, `status`, `executedAt`. Default: `executedAt` |
| `order`          | `string (enum)`     | No       | Sort order: `asc`, `desc`. Default: `asc`                                            |
| `payId`          | `string (guid)`     | No       | Filter by payment ID                                                                 |
| `referenceId`    | `string (15)`       | No       | RRN code for instant payments                                                        |
| `qrId`           | `string (guid)`     | No       | Filter by QR code ID                                                                 |
| `extensionId`    | `string (guid)`     | No       | Filter by QR extension ID                                                            |
| `orderId`        | `string (100)`      | No       | Filter by merchant order identifier                                                  |
| `amountFrom`     | `number (decimal)`  | No       | Filter by minimum amount (inclusive)                                                 |
| `amountTo`       | `number (decimal)`  | No       | Filter by maximum amount (inclusive)                                                 |
| `description`    | `string (500)`      | No       | Filter by description                                                                |
| `payerName`      | `string (200)`      | No       | Filter by payer name                                                                 |
| `payerIban`      | `string (200)`      | No       | Filter by payer IBAN                                                                 |
| `status`         | `string (enum)`     | No       | Filter by payment status: `Executed`, `Refunded`                                     |
| `executedAtFrom` | `string (datetime)` | No       | Filter by execution date — from (ISO 8601-1:2019 format)                             |
| `executedAtTo`   | `string (datetime)` | No       | Filter by execution date — to (ISO 8601-1:2019 format)                               |
| `terminalId`     | `string (100)`      | No       | Filter by terminal ID (provided by the bank)                                         |

***

**Example request**

```bash
curl -G "https://api.example.com/v2/mia/payments" \
  -H "Authorization: Bearer {{access_token}}" \
  --data-urlencode "count=10" \
  --data-urlencode "offset=0" \
  --data-urlencode "qrId=789e0123-f456-7890-a123-456789012345" \
  --data-urlencode "sortBy=executedAt" \
  --data-urlencode "order=asc"
```

***

**Response parameters**

| Name                         | Type                | Description                                        |
| ---------------------------- | ------------------- | -------------------------------------------------- |
| `result.totalCount`          | `integer`           | Total number of payments matching the filters      |
| `result.items[]`             | `array`             | List of payment objects                            |
| `result.items[].payId`       | `string (guid)`     | Unique ID of the payment                           |
| `result.items[].referenceId` | `string (15)`       | RRN code for the instant payment service           |
| `result.items[].qrId`        | `string (guid)`     | QR code ID                                         |
| `result.items[].extensionId` | `string (guid)`     | QR extension ID                                    |
| `result.items[].orderId`     | `string (100)`      | Merchant order ID                                  |
| `result.items[].amount`      | `number (decimal)`  | Payment amount                                     |
| `result.items[].commission`  | `number (decimal)`  | Applied commission                                 |
| `result.items[].currency`    | `string (enum)`     | Payment currency (e.g.,`MDL`, ISO 4217 format)     |
| `result.items[].description` | `string (500)`      | Order/payment description                          |
| `result.items[].payerName`   | `string (200)`      | Abbreviated name of the payer                      |
| `result.items[].payerIban`   | `string (200)`      | Payer’s IBAN                                       |
| `result.items[].status`      | `string (enum)`     | Payment status: `Executed`, `Refunded`             |
| `result.items[].executedAt`  | `string (datetime)` | Execution date and time (ISO 8601-1:2019)          |
| `result.items[].refundedAt`  | `string (datetime)` | Refund date and time (if any, ISO 8601-1:2019)     |
| `result.items[].terminalId`  | `string (100)`      | Terminal ID provided by the bank                   |
| `ok`                         | `boolean`           | `true` if the request was processed without errors |
| `errors[]`                   | `array`             | List of errors (if `ok = false`)                   |
| `errors[].errorCode`         | `string`            | Error code                                         |
| `errors[].errorMessage`      | `string`            | Error description                                  |

***

**Example response**

```json
{
  "result": {
    "totalCount": 42,
    "items": [
      {
        "payId": "123e4567-e89b-12d3-a456-426614174000",
        "referenceId": "QR000123456789",
        "qrId": "789e0123-f456-7890-a123-456789012345",
        "extensionId": "40e6ba44-7dff-48cc-91ec-386a38318c68",
        "amount": 50.00,
        "commission": 0.50,
        "currency": "MDL",
        "description": "Payment for order #123",
        "payerName": "John D.",
        "payerIban": "MD24AG00225100013104168",
        "status": "Executed",
        "executedAt": "2024-08-05T10:32:28+03:00",
        "terminalId": "P011111"
      },
      {
        "payId": "456e7890-a12b-34cd-5678-9e01f23g4567",
        "referenceId": "QR000123456780",
        "qrId": "789e0123-f456-7890-a123-456789012345",
        "extensionId": "37efb479-c41b-4a39-bd27-ea1aef05134f",
        "amount": 100.00,
        "commission": 1.00,
        "currency": "MDL",
        "description": "Payment for order #1234",
        "payerName": "Jane S.",
        "payerIban": "MD24AG000225100014156789",
        "status": "Refunded",
        "executedAt": "2024-08-04T09:15:00+03:00",
        "refundedAt": "2024-08-05T09:17:05+03:00",
        "terminalId": "P011111"
      }
    ]
  },
  "ok": true
}
```