# Get Payouts

**Method:** `GET`

**Path:** `/payouts/v3/payments`

**Category:** Payouts

**Authentication:** Required

## Description

Retrieves payout details. Use paymentReferenceId or clientReferenceId
to fetch a specific payout, or requestReferenceId to fetch all payouts
associated with a single request. Supports filtering by mode, status,
and date range.


## Query Parameters

- `paymentReferenceId` (`string`) — Unique identifier of the payment in Pine Labs database.
- `clientReferenceId` (`string`) — Unique client reference provided when creating the payout.
- `requestReferenceId` (`string`) — Unique identifier of the request in Pine Labs database.
- `bankTransactionReferenceId` (`string`) — Unique Transaction Reference (UTR) from the bank.
- `mode` (`UPI | IMPS | NEFT | RTGS`) — Filter by payment mode.
- `dateFrom` (`string`) — Fetch payouts initiated after this date (ISO 8601 UTC).
- `dateTo` (`string`) — Fetch payouts initiated before this date (ISO 8601 UTC).
- `status` (`SCHEDULED | PENDING | PROCESSING | PROCESSED | SUCCESS | FAILED`) — Filter by payout status.
- `page` (`string`) — Page number (default 1).
- `count` (`string`) — Number of records per page.

## Responses

- `200` — Payout records retrieved successfully.
- `400` — 
- `401` — 
- `403` — 
- `500` — 

### Response Schema

- `payments` (`GetPayoutsPaymentItem[]`) — List of payout records matching the query.
  - `clientReferenceId` (`string`) — Unique identifier to track the payout.
  - `paymentReferenceId` (`string`) — Unique identifier of the payment in Pine Labs database.
  - `bankTransactionReferenceId` (`string`) — Unique Transaction Reference (UTR) from the bank.
  - `mode` (`UPI | IMPS | NEFT | RTGS`) — Payment mode used for the payout.
  - `amount` (`object`) — Payout monetary amount with currency. For payout creation, minimum ₹1 (100 paisa), maximum ₹10 lakh (100000000 paisa).
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR). Minimum ₹1 (100), maximum ₹10 lakh (100000000).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `accountNumber` (`string`) — Beneficiary's bank account number (may be masked).
  - `payeeName` (`string`) — Name of the beneficiary.
  - `fees` (`object`) — Monetary amount with currency (no min/max constraints). Used for fees, tax, and balance values.
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `tax` (`object`) — Monetary amount with currency (no min/max constraints). Used for fees, tax, and balance values.
    - `value` (`integer`) **required** — Amount in the smallest currency unit (paisa for INR).
    - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

  - `remarks` (`string`) — Description or reference text for the transaction.
  - `status` (`SCHEDULED | PENDING | PROCESSING | PROCESSED | SUCCESS | FAILED`) — Current payout status.
  - `message` (`string`) — Message corresponding to the payout status.
  - `createdAt` (`string`) — Timestamp when the payout request was received (ISO 8601 UTC).
  - `updatedAt` (`string`) — Timestamp when the payout record was last updated (ISO 8601 UTC).
  - `scheduledAt` (`string`) — Scheduled execution time in UTC.

- `totalRecords` (`integer`) — Total number of records matching the query.
- `nextPage` (`integer`) — Next page number in the result set.
- `totalPages` (`integer`) — Total number of pages in the result set.
- `_links` (`PayoutLink[]`) — HATEOAS pagination links.
  - `rel` (`string`) — Relation type of the link.
  - `href` (`string`) — URL of the related resource.


### Example Response

```json
{
  "payments": [
    {
      "clientReferenceId": "0171c4c0-f50a-4151-b39b-63c87a3c0cd6",
      "paymentReferenceId": "txn-b03ee63e412a4ecf88b6bdb08a6632c3",
      "bankTransactionReferenceId": "664816162868",
      "mode": "IMPS",
      "amount": {
        "value": 4900,
        "currency": "INR"
      },
      "accountNumber": "*******9300",
      "payeeName": "Kevin Bob",
      "fees": {
        "value": 0,
        "currency": "INR"
      },
      "tax": {
        "value": 0,
        "currency": "INR"
      },
      "remarks": "REFUND",
      "status": "SUCCESS",
      "message": "Payment instruction successfully executed with bank",
      "createdAt": "2025-07-16T10:26:06Z",
      "updatedAt": "2025-07-16T10:28:06Z",
      "scheduledAt": "2025-07-16T10:26:06Z"
    }
  ],
  "totalRecords": 1,
  "nextPage": 1,
  "totalPages": 1,
  "_links": [
    {
      "rel": "status",
      "href": "/payouts/v3/payments?paymentReferenceId=txn-b03ee63e412a4ecf88b6bdb08a6632c3"
    }
  ]
}
```

---

Reference: https://localhost:3000/api/payouts/list-payouts