> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eximpe.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Payments
> Page through your payments, newest first, filtered by status, method, date or reference.
## Overview
Returns your payments a page at a time, newest first. Each entry carries the payment's `status`, its buyer, its amount and the order behind it. To get the full record of one payment — settlement, refunds and method-of-payment details — call [Get Payment](/api-reference/v3/payment/get) with its `payment_id`.
**PSPs get one list covering every payment they can act for**: their own and all their sub-merchants'. `merchant` on each entry says whose it is. To narrow the list to one sub-merchant, send that sub-merchant's ID in `X-Merchant-ID`, or pass it as the `merchant` filter.
## Query Parameters
All parameters are optional, and you can combine filters.
| Name | Type | Default | Description |
| - | - | - | - |
| `page` | integer | `1` | Page number. |
| `page_size` | integer | `250` | Payments per page. Values above `1000` are capped at `1000`. |
| `ordering` | string | `-created_at` | `created_at`, `last_updated_at` or `payment_completed_at`. Prefix with `-` for descending. |
| `search` | string | | Case-insensitive partial match across payment ID, order ID, reference ID, invoice number, buyer name, buyer email and bank reference. |
| `payment_id` | string | | Exact payment ID. |
| `order_id` | string | | Exact order ID. |
| `reference_id` | string | | Exact reference ID. Case-sensitive. |
| `invoice_number` | string | | Exact invoice number. Case-sensitive. |
| `buyer_name` | string | | Exact buyer name. Case-sensitive: `John Doe` matches but `john` does not. Use `search` for a partial match. |
| `merchant` | string | | Merchant ID. |
| `currency` | string | | ISO 4217 code, e.g. `INR`. |
| `mop_type` | string | | `upi`, `credit_card`, `debit_card`, `net_banking`, `qr`. |
| `collection_mode` | string | | `hosted_payment`, `payment_link`, `s2s`. |
| `status` | string | | `pending`, `captured`, `failed`. |
| `from_created_at` / `to_created_at` | date | | Created within this range, `YYYY-MM-DD` in UTC. Both ends are included. |
| `from_payment_completed_at` / `to_payment_completed_at` | date | | Completed within this range, `YYYY-MM-DD` in UTC. Both ends are included. |
`mop_type`, `collection_mode` and `status` are case-insensitive and take several values separated by commas, e.g. `status=captured,failed`.
## Pagination
`data` wraps the page:
| Field | Description |
| - | - |
| `count` | Total payments across all pages |
| `page` | This page's number |
| `page_size` | Payments per page |
| `next` | Full URL of the next page, or `null` on the last one |
| `previous` | Full URL of the previous page, or `null` on the first one |
| `results` | The payments on this page |
Follow `next` until it is `null`. A page past the last one is not returned empty. It is refused with a `500` whose `error.details.error` is `"Invalid page."`.
## Payment status
| `status` | Meaning |
| - | - |
| `pending` | Started, with no final outcome yet. |
| `captured` | Paid. |
| `failed` | Declined, abandoned, or expired before it completed. `comment` says why when there is a reason. |
**Expired payments read differently in the list and in the filter.** A pending payment that passes its expiry is shown as `failed` here, but the `status` filter matches the status as recorded. So `status=pending` can return entries that read `failed`, and `status=failed` will not find them. [Get Payment](/api-reference/v3/payment/get) shows the recorded status, so the same payment reads `pending` there.
## Response Fields
* `payment_id` is the payment's ID (`PR` followed by 10 digits). [Get Payment](/api-reference/v3/payment/get) takes it.
* `amount.amount` and `amount.total_amount` are decimal strings without trailing zeros, e.g. `"1500"` or `"2499.5"`. Parse them as decimals, never as floats. `total_amount` adds GST where GST applies; otherwise it equals `amount`.
* `mop_type` is the method the buyer paid with, in lowercase (`upi`, `credit_card`). It is `null` when no method was chosen.
* `comment` says why a payment failed, or what state it is in, when there is something to say; otherwise it is `null`.
* `order_id` is the order behind the payment (`OD` followed by 10 digits). One order can have several payments, one per attempt.
* `created_at` is UTC with microseconds, e.g. `2026-10-15T06:44:13.414209Z`.
The response is the same whatever `X-API-Version` you send. v1, v2 and v3 integrations share this endpoint and its response.
## OpenAPI
````yaml openapi/v3-payments.json GET /pg/payments/
openapi: 3.0.3
info:
title: EximPe Payment Gateway API — v3 Payments
version: 3.0.0
description: >-
List and retrieve payments on the v3 API. v1 and v2 use the same paths and
return the same response; this spec carries the v3 reference.
servers:
- url: https://api-pacb-uat.eximpe.com
description: Payment Gateway Sandbox URL
security: []
tags:
- name: Payments
paths:
/pg/payments/:
get:
tags:
- Payments
summary: List Payments
description: >-
Return a paginated list of payments, newest first, with optional
filters.
operationId: v3_listPayments
parameters:
- name: page
in: query
required: false
description: >-
Page number, starting at 1. Stop when `next` is null: a page past
the last one is refused with a 500.
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
required: false
description: Payments per page. Values above 1000 are capped at 1000.
schema:
type: integer
minimum: 1
maximum: 1000
default: 250
- name: ordering
in: query
required: false
description: >-
Sort order. Prefix with `-` for descending. An unrecognised value is
ignored.
schema:
type: string
enum:
- '-created_at'
- created_at
- '-last_updated_at'
- last_updated_at
- '-payment_completed_at'
- payment_completed_at
default: '-created_at'
- name: search
in: query
required: false
description: >-
Case-insensitive substring match across payment ID, order ID,
reference ID, invoice number, buyer name, buyer email and bank
reference.
schema:
type: string
- name: payment_id
in: query
required: false
description: Exact payment ID.
schema:
type: string
- name: order_id
in: query
required: false
description: Exact order ID.
schema:
type: string
- name: reference_id
in: query
required: false
description: Exact reference ID (case-sensitive).
schema:
type: string
- name: invoice_number
in: query
required: false
description: Exact invoice number (case-sensitive).
schema:
type: string
- name: buyer_name
in: query
required: false
description: Exact buyer name (case-sensitive). Use `search` for a partial match.
schema:
type: string
- name: merchant
in: query
required: false
description: Merchant ID. PSPs can use it to narrow the list to one sub-merchant.
schema:
type: string
- name: currency
in: query
required: false
description: ISO 4217 currency code, e.g. `INR`.
schema:
type: string
- name: mop_type
in: query
required: false
description: Method of payment. Case-insensitive; comma-separate several values.
schema:
type: string
example: upi,credit_card
- name: collection_mode
in: query
required: false
description: >-
`hosted_payment`, `payment_link` or `s2s`. Case-insensitive;
comma-separate several values.
schema:
type: string
- name: status
in: query
required: false
description: >-
`pending`, `captured` or `failed`. Case-insensitive; comma-separate
several values. Matches the status as recorded — see the note on
expired payments.
schema:
type: string
example: captured
- name: from_created_at
in: query
required: false
description: Created on or after this date (`YYYY-MM-DD`, UTC).
schema:
type: string
format: date
- name: to_created_at
in: query
required: false
description: >-
Created on or before this date (`YYYY-MM-DD`, UTC). The whole day is
included.
schema:
type: string
format: date
- name: from_payment_completed_at
in: query
required: false
description: Completed on or after this date (`YYYY-MM-DD`, UTC).
schema:
type: string
format: date
- name: to_payment_completed_at
in: query
required: false
description: >-
Completed on or before this date (`YYYY-MM-DD`, UTC). The whole day
is included.
schema:
type: string
format: date
responses:
'200':
description: A page of payments
content:
application/json:
schema:
$ref: '#/components/schemas/v3_ListPaymentsResponse'
examples:
One page:
summary: One page
value:
success: true
message: Domestic payment requests retrieved successfully
data:
count: 2
page: 1
page_size: 250
next: null
previous: null
results:
- payment_id: PR4350279153
merchant:
id: '4417290356'
name: Acme Exports
reference_id: ORD-2026-000123
buyer:
name: Rahul Sharma
email: rahul.sharma@example.com
phone: '+919876543210'
order_id: OD8196969047
invoice_number: INV2026000123
amount:
amount: '1500'
total_amount: '1500'
currency: INR
created_at: '2026-10-15T06:44:13.414209Z'
comment: null
mop_type: upi
status: captured
- payment_id: PR1352481140
merchant:
id: '4417290356'
name: Acme Exports
reference_id: ORD-2026-000118
buyer:
name: Priya Nair
email: priya.nair@example.com
phone: '+919812345678'
order_id: OD3094308378
invoice_number: INV2026000118
amount:
amount: '2499.5'
total_amount: '2499.5'
currency: INR
created_at: '2026-10-14T08:22:59.613699Z'
comment: Payment abandoned by user
mop_type: credit_card
status: failed
'401':
description: Missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/v3_ErrorResponse'
examples:
Missing credentials:
summary: Missing credentials
value:
success: false
error:
code: ERR_AUTH_000
message: Missing credentials
details:
authentication: Missing credentials.
'500':
description: Invalid filter value, invalid date or a page past the last one
content:
application/json:
schema:
$ref: '#/components/schemas/v3_ErrorResponse'
examples:
Invalid status:
summary: Invalid status
value:
success: false
error:
code: 40350
message: Failed to retrieve domestic payment requests
details:
error: >-
{'status': ErrorDetail(string='Invalid value. Must be
one of: PENDING, CAPTURED, FAILED, INVALID',
code='invalid')}
Page past the last one:
summary: Page past the last one
value:
success: false
error:
code: 40350
message: Failed to retrieve domestic payment requests
details:
error: Invalid page.
security:
- clientAuth: []
clientSecretAuth: []
apiVersionHeader: []
- clientAuth: []
clientSecretAuth: []
merchantAuth: []
apiVersionHeader: []
components:
schemas:
v3_ListPaymentsResponse:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
count:
type: integer
description: Total payments across all pages.
page:
type: integer
description: This page's number.
page_size:
type: integer
description: Payments per page.
next:
type: string
nullable: true
description: Full URL of the next page, or `null` on the last one.
previous:
type: string
nullable: true
description: Full URL of the previous page, or `null` on the first one.
results:
type: array
items:
$ref: '#/components/schemas/v3_PaymentListItem'
v3_ErrorResponse:
type: object
required:
- success
- error
properties:
success:
type: boolean
enum:
- false
description: >-
Indicates if the request was successful. Always false for error
responses.
error:
$ref: '#/components/schemas/v3_ErrorDetails'
v3_PaymentListItem:
type: object
properties:
payment_id:
type: string
description: Payment ID — `PR` followed by 10 digits.
merchant:
type: object
nullable: true
description: >-
Whose payment this is. For a PSP, one of its sub-merchants or the
PSP itself.
properties:
id:
type: string
description: Merchant ID.
name:
type: string
description: Merchant display name.
reference_id:
type: string
description: Your reference for the order.
buyer:
type: object
nullable: true
properties:
name:
type: string
description: Buyer name.
email:
type: string
description: Buyer email.
phone:
type: string
description: Buyer phone, with country code.
nullable: true
order_id:
type: string
description: The order this payment belongs to — `OD` followed by 10 digits.
invoice_number:
type: string
description: The order's invoice number.
amount:
type: object
properties:
amount:
type: string
description: >-
Order amount as a decimal string without trailing zeros, e.g.
`"1500"`, `"2499.5"`.
total_amount:
type: string
description: >-
Amount including GST where GST applies; otherwise equal to
`amount`. Same format as `amount`.
currency:
type: string
description: ISO 4217 currency code.
nullable: true
created_at:
type: string
format: date-time
description: When the payment was created, UTC with microseconds.
comment:
type: string
description: >-
Why the payment failed or what state it is in, when there is
something to say; otherwise `null`.
nullable: true
mop_type:
type: string
description: Method of payment, lowercase.
nullable: true
enum:
- upi
- credit_card
- debit_card
- net_banking
- qr
- null
status:
type: string
description: >-
Payment status. A pending payment past its expiry reads `failed`
here.
enum:
- pending
- captured
- failed
v3_ErrorDetails:
type: object
required:
- code
- message
properties:
code:
description: >-
Error code (e.g., ERR_ORDER_002). The list endpoint's own failure
sends a number (40350).
oneOf:
- type: string
- type: integer
message:
type: string
description: Error message
details:
description: >-
What failed. Usually an object keyed by the offending field and
nested the way the request is (e.g. buyer.address.postal_code), with
one message per field. A purpose_code refusal sends a single string
instead.
oneOf:
- type: object
additionalProperties: true
- type: string
securitySchemes:
clientAuth:
type: apiKey
name: X-Client-ID
in: header
description: >-
**Client Application ID** - Your unique application identifier used to
authenticate API requests. You can find your Client ID in the Developer
Settings section of the merchant dashboard.
x-displayName: Client ID
x-example: your-client-id
clientSecretAuth:
type: apiKey
name: X-Client-Secret
in: header
description: >-
**Client Secret Key** - Your secret key used alongside the Client ID for
secure authentication. Keep this confidential and never expose it in
client-side code. Available in the Developer Settings section of the
merchant dashboard.
x-displayName: Client Secret
x-example: your-client-secret
apiVersionHeader:
type: apiKey
name: X-API-Version
in: header
description: >-
**API Version** - Specifies which version of the API to use (e.g.,
'1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which
API version your integration uses. Default version information is
available in the Developer Settings.
x-displayName: API Version
x-example: 3.0.0
merchantAuth:
type: apiKey
name: X-Merchant-ID
in: header
description: >-
**Merchant Identifier** - The unique ID for the merchant account. This
is required for PSP (Payment Service Provider) merchants who manage
multiple merchant accounts. You can find merchant IDs in the Merchant
Management section of the dashboard.
x-displayName: Merchant ID
x-example: your-merchant-id
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.