⬆️GET Single Payout

In this section, you’ll learn how to retrieve a singl payout records from your PayRam server, including their details and current statuses.

Check the current status of a payout by its id (the id returned by Create Payout). This is the endpoint to poll after creating a payout.

---

Authentication

Project-API-key only. Results are scoped to the API key’s own project: a payout id that belongs to a different project returns 404 (not another project’s data). Type-restricted to merchant payouts (payout_merchant).

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

Endpoint

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

Path parameter	Description	Example
id	The payout id returned by Create Payout.	120

Headers

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

Example Request

curl --location --request GET \
  '${BASE_URL}/api/v1/withdrawal/120/merchant' \
  --header 'API-Key: <API_KEY>' \
  --header 'Content-Type: application/json'

Example Response

200 OK — a single payout object (same shape as the items in Get All Payouts):

{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "updatedAt": "2026-06-19T13:18:02.114Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "fee": "0.000412",
  "fromAddress": "0x21d4cF2E…EA8d45",
  "toAddress": "0x9F8E7D6C…65432",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "[e-mail]",
  "txHash": "0xabc123…def456",
  "status": "sent",
  "type": "payout_merchant",
  "attributes": null,
  "failureReason": null,
  "webhookStatus": "received",
  "createdBy": "user"
}

See Key Response Fields in Get All Payouts for the meaning of every field.

Payout statuses

Check the status field to know where the payout is in its lifecycle:

Status	Meaning
pending-otp-verification	Waiting for OTP verification before processing.
pending-approval	Held for manual approval — the payout exceeded the auto-approve amount or an hourly/daily limit. attributes.approvalReason explains why.
pending	Approved (or auto-approved) and queued for on-chain processing.
initiated	Broadcast to the blockchain (txHash is set); awaiting confirmation.
sent	Transaction confirmed on-chain.
processed	Confirmed and recorded in PayRam’s accounting — fully complete.
failed	Processing failed — see failureReason for the specific cause.
rejected	Declined by an admin (or the system).
cancelled	Intentionally stopped before being sent/processed.

Terminal states: processed, failed, rejected, cancelled — stop polling once a payout reaches one of these.

Polling guidance

If you aren’t using Payout Webhooks (recommended — see the last section), poll this endpoint until the payout reaches a terminal state. A sensible cadence is every few seconds right after creation, backing off to longer intervals; a payout typically reaches sent/processed within a few minutes once it’s on-chain. For a pending-approval payout, poll until an admin approves it (then it continues to sent/processed) or rejects it.

HTTP	When
401	Missing/invalid API-Key, or a non-project key.
404	No payout with that id in your project (or the endpoint isn’t present on PayRam < v3.1.1). Response: { "message": "not found" }.