↕️GET All Payouts

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
BASE_URL	Your PayRam server URL, e.g. https://yourdomain.com
Method	GET

BASE_URL: use your plain HTTPS domain (https://yourdomain.com).

Headers

Header	Required	Example
API-Key	Yes	be703fa47ebe07121102ee260fb3d5c0 (project key)
Content-Type	Yes	application/json

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 [] may be repeated (e.g. ?status=sent&status=processed).

Pagination and Sorting

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

⚠️ sortBy must be a real snake_case column (created_at, not createdAt) — a camelCase value returns 500.

⚠️ There is no “return everything”: omitting limit returns at most 100. Page with offset (or greaterThanID) until a page returns fewer than limit rows.

Filters

Parameter	Description	Example
status []	Payout status (see lifecycle in the Overview).	status=sent
types []	Payout type — for merchant payouts use payout_merchant.	types=payout_merchant
blockchainCode []	Chain code.	blockchainCode=ETH
toAddress []	Recipient address(es).
fromAddress []	Sending hot-wallet address(es).
recipientEmails []	Recipient email(s).	recipientEmails=[e-mail]
recipientIDs []	Recipient member IDs.
search	Free-text, case-insensitive substring across recipient email, from address, to address, tx hash.	search=0xabc

Example Request

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

200 OK — a JSON array of payout objects:

[
  {
    "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": "[e-mail]",
    "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": "[e-mail]",
    "txHash": null,
    "status": "pending-approval",
    "type": "payout_merchant",
    "attributes": "{\"approvalReason\":\"daily_limit_exceeded\"}",
    "failureReason": null,
    "createdBy": "user"
  }
]

Key Response Fields

Field	Meaning
id	Payout ID (use with GET /withdrawal/{id}/merchant).
status	Lifecycle state (see the Overview).
currencyType	token (ERC20/TRC20, e.g. USDC/USDT) or coin (native ETH/POL/TRX).
amount / amountInUSD	Token amount / USD value at creation.
priceInUSD	Unit price used at creation (stablecoins = 1).
fee	On-chain network fee (set once sent).
fromAddress	Project hot wallet paying out.
toAddress / tokenAddress	Recipient; token contract (0x000…000 for native coins).
txHash	On-chain hash (set from initiated onward).
attributes	JSON; for pending-approval contains approvalReason (why approval is required).
failureReason	Specific cause on failed/stuck payouts.
webhookStatus	Payout webhook delivery state — received (your endpoint accepted it) or failed (delivery failed after retries).
createdBy	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	code	When
401	UNAUTHORIZED	Missing/invalid API-Key, or a non-project key (JWT / member-linked).
400	BAD_REQUEST	Malformed query parameters.
404	—	Endpoint not present (PayRam < v3.1.1).
500	INTERNAL_SERVER_ERROR	Invalid sortBy (camelCase instead of snake_case), or server error.