> For the complete documentation index, see [llms.txt](https://docs.payram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payram.com/api-integration/payouts-apis/get-all-payouts.md).

# GET All Payouts

<figure><img src="/files/QwWj578lu4ZFZXtXKuJq" alt=""><figcaption></figcaption></figure>

Retrieve payout (merchant withdrawal) records for your project — with filtering, sorting, and pagination.

### Authentication

This endpoint is **project-API-key only**. Generate a key per project from the PayRam dashboard (Project → API Keys). Results are automatically scoped to that key’s project — you only ever see your own project’s payouts.

> **Requires PayRam v3.1.1 or later.** On earlier versions this endpoint returns 404.

### Endpoint

```
GET {BASE_URL}/api/v1/withdrawal/merchant
```

| Item                                            | Value                                                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
| <mark style="color:$warning;">`BASE_URL`</mark> | Your PayRam server URL, e.g. <mark style="color:$warning;">`https://yourdomain.com`</mark> |
| Method                                          | <mark style="color:$warning;">`GET`</mark>                                                 |

BASE\_URL: use your plain HTTPS domain (<mark style="color:$warning;">`https://yourdomain.com`</mark>).

### Headers

| Header                                              | Required | Example                                                                               |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> (project key) |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                               |

> You can generate a unique API key for each project from the PayRam dashboard, so you can manage and track payouts separately per project.

### Query Parameters

All optional. Parameters marked <mark style="color:$warning;">`[]`</mark> may be repeated (e.g. <mark style="color:$warning;">`?status=sent&status=processed`</mark>).

### Pagination and Sorting

| Parameter                                                                                                  | Description                                                                                                                                                                                                                                                                                            | Example                                                     |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| <mark style="color:$warning;">`limit`</mark>                                                               | Records per page. **Defaults to 100 and is capped at 100** (larger values are clamped).                                                                                                                                                                                                                | <mark style="color:$warning;">`20`</mark>                   |
| <mark style="color:$warning;">`offset`</mark>                                                              | Starting offset for paging.                                                                                                                                                                                                                                                                            | <mark style="color:$warning;">`40`</mark>                   |
| <mark style="color:$warning;">`order`</mark>                                                               | <mark style="color:$warning;">`ASC`</mark> or <mark style="color:$warning;">`DESC`</mark>. Default <mark style="color:$warning;">`DESC`</mark>.                                                                                                                                                        | <mark style="color:$warning;">`DESC`</mark>                 |
| <mark style="color:$warning;">`sortBy`</mark>                                                              | Column to sort by — **use the snake\_case DB column** (<mark style="color:$warning;">`created_at`</mark>, <mark style="color:$warning;">`amount`</mark>, <mark style="color:$warning;">`id`</mark>, <mark style="color:$warning;">`status`</mark>). Default <mark style="color:$warning;">`id`</mark>. | <mark style="color:$warning;">`created_at`</mark>           |
| <mark style="color:$warning;">`greaterThanID`</mark> / <mark style="color:$warning;">`lessThanID`</mark>   | Keyset pagination by id (alternative to <mark style="color:$warning;">`offset`</mark>).                                                                                                                                                                                                                | <mark style="color:$warning;">`200`</mark>                  |
| <mark style="color:$warning;">`createdAfter`</mark> / <mark style="color:$warning;">`createdBefore`</mark> | Creation-time range (RFC3339).                                                                                                                                                                                                                                                                         | <mark style="color:$warning;">`2026-06-01T00:00:00Z`</mark> |
| <mark style="color:$warning;">`updatedAfter`</mark> / <mark style="color:$warning;">`updatedBefore`</mark> | Last-update range (RFC3339).                                                                                                                                                                                                                                                                           |                                                             |
| <mark style="color:$warning;">`startDate`</mark> / <mark style="color:$warning;">`endDate`</mark>          | Creation-date range (RFC3339).                                                                                                                                                                                                                                                                         |                                                             |

> ⚠️ <mark style="color:$warning;">`sortBy`</mark> must be a real snake\_case column (<mark style="color:$warning;">`created_at`</mark>, **not** <mark style="color:$warning;">`createdAt`</mark>) — a camelCase value returns **500**.
>
> ⚠️ There is **no “return everything”**: omitting <mark style="color:$warning;">`limit`</mark> returns at most 100. Page with <mark style="color:$warning;">`offset`</mark> (or <mark style="color:$warning;">`greaterThanID`</mark>) until a page returns fewer than <mark style="color:$warning;">`limit`</mark> rows.

### Filters

| Parameter                                                                                        | Description                                                                                          | Example                                                              |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <mark style="color:$warning;">`status`</mark> <mark style="color:$warning;">`[]`</mark>          | Payout status (see lifecycle in the Overview).                                                       | <mark style="color:$warning;">`status=sent`</mark>                   |
| <mark style="color:$warning;">`types`</mark> <mark style="color:$warning;">`[]`</mark>           | Payout type — for merchant payouts use <mark style="color:$warning;">`payout_merchant`</mark>.       | <mark style="color:$warning;">`types=payout_merchant`</mark>         |
| <mark style="color:$warning;">`blockchainCode`</mark> <mark style="color:$warning;">`[]`</mark>  | Chain code.                                                                                          | <mark style="color:$warning;">`blockchainCode=ETH`</mark>            |
| <mark style="color:$warning;">`toAddress`</mark> <mark style="color:$warning;">`[]`</mark>       | Recipient address(es).                                                                               |                                                                      |
| <mark style="color:$warning;">`fromAddress`</mark> <mark style="color:$warning;">`[]`</mark>     | Sending hot-wallet address(es).                                                                      |                                                                      |
| <mark style="color:$warning;">`recipientEmails`</mark> <mark style="color:$warning;">`[]`</mark> | Recipient email(s).                                                                                  | <mark style="color:$warning;">`recipientEmails=test@test.com`</mark> |
| <mark style="color:$warning;">`recipientIDs`</mark> <mark style="color:$warning;">`[]`</mark>    | Recipient member IDs.                                                                                |                                                                      |
| <mark style="color:$warning;">`search`</mark>                                                    | Free-text, case-insensitive substring across **recipient email, from address, to address, tx hash**. | <mark style="color:$warning;">`search=0xabc`</mark>                  |

### Example Request

```bash
curl --location --request GET \
  '${BASE_URL}/api/v1/withdrawal/merchant?limit=10&offset=0&order=DESC&sortBy=created_at&status=sent' \
  --header 'API-Key: <API_KEY>' \
  --header 'Content-Type: application/json'
```

### Example Response

<mark style="color:$warning;">`200 OK`</mark> — a JSON **array** of payout objects:

```json
[
  {
    "id": 159,
    "createdAt": "2026-06-19T18:44:02.511Z",
    "updatedAt": "2026-06-19T18:45:10.882Z",
    "blockchainCode": "BASE",
    "currencyCode": "USDC",
    "currencyType": "token",
    "amount": "1.00",
    "priceInUSD": "1",
    "amountInUSD": "1.000000",
    "fee": "0.000021",
    "fromAddress": "0x21d4cF2E…EA8d45",
    "toAddress": "0x6df1fc38…133ddf",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "recipientEmail": "akash@payram.com",
    "txHash": "0xf382aa63…ea103b",
    "uniqueTxHash": "0xf382aa63…ea103b-12",
    "txIndex": 12,
    "blockHash": "0x…",
    "blockNumber": 21897412,
    "status": "processed",
    "type": "payout_merchant",
    "attributes": null,
    "failureReason": null,
    "webhookStatus": "received",
    "retryCount": 0,
    "timestamp": "2026-06-19T18:44:02.511Z",
    "memberID": 1,
    "externalPlatformID": 1,
    "currencyID": 3,
    "blockchainID": 4,
    "createdBy": "user"
  },
  {
    "id": 160,
    "blockchainCode": "POLYGON",
    "currencyCode": "POL",
    "currencyType": "coin",
    "amount": "14.00",
    "amountInUSD": "1.068102",
    "toAddress": "0xd553af7e…f7f11f",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "recipientEmail": "akash@payram.com",
    "txHash": null,
    "status": "pending-approval",
    "type": "payout_merchant",
    "attributes": "{\"approvalReason\":\"daily_limit_exceeded\"}",
    "failureReason": null,
    "createdBy": "user"
  }
]
```

### Key Response Fields

| Field                                                           | Meaning                                                                                                                                                                                       |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`id`</mark>                       | Payout ID (use with <mark style="color:$warning;">`GET /withdrawal/{id}/merchant`</mark>).                                                                                                    |
| <mark style="color:$warning;">`status`</mark>                   | Lifecycle state (see the Overview).                                                                                                                                                           |
| <mark style="color:$warning;">`currencyType`</mark>             | <mark style="color:$warning;">`token`</mark> (ERC20/TRC20, e.g. USDC/USDT) or <mark style="color:$warning;">`coin`</mark> (native ETH/POL/TRX).                                               |
| <mark style="color:$warning;">`amount / amountInUSD`</mark>     | Token amount / USD value at creation.                                                                                                                                                         |
| <mark style="color:$warning;">`priceInUSD`</mark>               | Unit price used at creation (stablecoins = <mark style="color:$warning;">`1`</mark>).                                                                                                         |
| <mark style="color:$warning;">`fee`</mark>                      | On-chain network fee (set once sent).                                                                                                                                                         |
| <mark style="color:$warning;">`fromAddress`</mark>              | Project hot wallet paying out.                                                                                                                                                                |
| <mark style="color:$warning;">`toAddress / tokenAddress`</mark> | Recipient; token contract (<mark style="color:$warning;">`0x000…000`</mark> for native coins).                                                                                                |
| <mark style="color:$warning;">`txHash`</mark>                   | On-chain hash (set from <mark style="color:$warning;">`initiated`</mark> onward).                                                                                                             |
| <mark style="color:$warning;">`attributes`</mark>               | JSON; for <mark style="color:$warning;">`pending-approval`</mark> contains <mark style="color:$warning;">`approvalReason`</mark> (why approval is required).                                  |
| <mark style="color:$warning;">`failureReason`</mark>            | Specific cause on failed/stuck payouts.                                                                                                                                                       |
| <mark style="color:$warning;">`webhookStatus`</mark>            | Payout webhook delivery state — <mark style="color:$warning;">`received`</mark> (your endpoint accepted it) or <mark style="color:$warning;">`failed`</mark> (delivery failed after retries). |
| <mark style="color:$warning;">`createdBy`</mark>                | Origin of the payout.                                                                                                                                                                         |

### Pagination Pattern

```
GET …/withdrawal/merchant?limit=100&offset=0&sortBy=created_at&order=DESC
GET …/withdrawal/merchant?limit=100&offset=100&sortBy=created_at&order=DESC
# stop when a page returns < limit rows
```

### Errors

| HTTP | <mark style="color:$warning;">`code`</mark>                  | When                                                                                                        |
| ---- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 401  | <mark style="color:$warning;">`UNAUTHORIZED`</mark>          | Missing/invalid <mark style="color:$warning;">`API-Key`</mark>, or a non-project key (JWT / member-linked). |
| 400  | <mark style="color:$warning;">`BAD_REQUEST`</mark>           | Malformed query parameters.                                                                                 |
| 404  | —                                                            | Endpoint not present (PayRam < v3.1.1).                                                                     |
| 500  | <mark style="color:$warning;">`INTERNAL_SERVER_ERROR`</mark> | Invalid <mark style="color:$warning;">`sortBy`</mark> (camelCase instead of snake\_case), or server error.  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payram.com/api-integration/payouts-apis/get-all-payouts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.