> 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 List the payouts your application created through the API (`createdBy: "user"`), with filters, sorting and pagination. This is by design: [dashboard payouts](/api-integration/payouts-apis/overview.md#two-kinds-of-merchant-payout) are managed in the dashboard (you can still read one by id with [GET Single Payout](/api-integration/payouts-apis/get-single-payout.md)). ### Endpoint ``` GET {BASE_URL}/api/v1/withdrawal/merchant ``` Header: `API-Key` — your project API key. ### Pagination and sorting | Parameter | Description | | --------- | -------------------------------------------------------------------------------------------------------------------- | | `limit` | 1–100. Default and maximum 100; `0` or less means the default (PayRam Core v3.9.0 and later). | | `offset` | Rows to skip. | | `sortBy` | A snake\_case column name, e.g. `created_at`, `updated_at`, `amount`, `amount_in_usd`, `status`, `id`. Default `id`. | | `order` | `asc` or `desc` (default `desc`; any other value means `desc`). | There is no total count. Page with `offset` until a page returns fewer rows than `limit`: ``` GET …/withdrawal/merchant?limit=100&offset=0&sortBy=created_at&order=desc GET …/withdrawal/merchant?limit=100&offset=100&sortBy=created_at&order=desc ``` ### Filters All optional. Parameters marked `[]` can be repeated (e.g. `?status=sent&status=processed`). | Parameter | Description | | -------------------------------- | --------------------------------------------------------------------------------------------------- | | `status` `[]` | Payout status — see [Status lifecycle](/api-integration/payouts-apis/overview.md#status-lifecycle). | | `types` `[]` | Payout type. API payouts are always `payout_merchant`. | | `blockchainCode` `[]` | Network code, e.g. `ETH`. | | `toAddress` `[]` | Recipient address. | | `fromAddress` `[]` | Sending hot-wallet address. | | `recipientEmails` `[]` | Recipient email. | | `search` | Case-insensitive substring match on recipient email, from address, to address and tx hash. | | `createdAfter` / `createdBefore` | Creation time range (RFC 3339, e.g. `2026-06-01T00:00:00Z`). | | `updatedAfter` / `updatedBefore` | Last-update time range (RFC 3339). | | `startDate` / `endDate` | Creation time range, inclusive (RFC 3339). | | `greaterThanID` / `lessThanID` | Only ids above / below this value — an alternative to `offset`. | ### Example request ```bash curl --location --request GET \ '${BASE_URL}/api/v1/withdrawal/merchant?limit=10&sortBy=created_at&order=desc&status=sent' \ --header 'API-Key: ' ``` ### Example response `200 OK` — a JSON array of payouts (empty array if none match): ```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", "priceInUSD": "1", "amountInUSD": "1", "fee": "0.000021", "fromAddress": "0x21d4cF2E…EA8d45", "toAddress": "0x6df1fc38…133ddf", "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipientEmail": "test@test.com", "txHash": "0xf382aa63…ea103b", "status": "sent", "type": "payout_merchant", "attributes": null, "webhookStatus": "received", "createdBy": "user", "externalPlatform": { "…": "…" } } ] ``` ### Response fields | Field | Meaning | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Payout id — use it with [GET Single Payout](/api-integration/payouts-apis/get-single-payout.md). | | `status` | See [Status lifecycle](/api-integration/payouts-apis/overview.md#status-lifecycle). | | `blockchainCode` / `currencyCode` | Network and token. | | `currencyType` | `token` (e.g. USDC, USDT) or `coin` (native ETH, POL, TRX). | | `amount` | Amount in the token, as sent. | | `priceInUSD` / `amountInUSD` | USD unit price and USD value at creation. | | `fee` | On-chain network fee paid for the transaction (set once sent). | | `fromAddress` | Project hot wallet the payout is sent from. | | `toAddress` | Recipient wallet. | | `tokenAddress` | Token contract (`0x000…000` for native coins). | | `recipientEmail` | Recipient email from the request. | | `txHash` | Transaction hash, set from `initiated` on. Can change while `initiated` — use the latest. | | `attributes` | `null`, or a **JSON-encoded string** — for `pending-approval` it holds `approvalReason`. | | `failureReason` | Why a payout failed or was rejected, or why a `pending` payout is not sent yet (for example, waiting for the hot wallet to be topped up). **Omitted** when there is no reason, for example once it is sent. | | `webhookStatus` | Result of the most recent webhook delivery: `received`, `failed`, or `null` (none attempted yet). | | `createdBy` | `user` (API payout) or `system` (dashboard payout). | | `createdAt` / `updatedAt` | ISO 8601 timestamps. | Other fields, including the nested `externalPlatform` object (your own project), are safe to ignore. ### Errors | HTTP | `code` | When | | ----- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `BAD_REQUEST` | Malformed query parameter (e.g. a non-numeric `limit`), or the removed `recipientIDs` filter — use `recipientEmails` (PayRam Core v3.9.0 and later). | | `401` | `UNAUTHORIZED` | Missing or invalid `API-Key`, or not a project key. | | `403` | `INSUFFICIENT_PERMISSIONS` | The key lacks payout read permission. | | `500` | `INTERNAL_SERVER_ERROR` | `sortBy` is not a real column (e.g. camelCase `createdAt`), or a server error. |