> 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.  |