> 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-single-payout.md).

# GET Single Payout

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

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 (<mark style="color:$warning;">`payout_merchant`</mark>).

> **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                                    |
| ----------------------------------------- | ---------------------------------------- | ------------------------------------------ |
| <mark style="color:$warning;">`id`</mark> | The payout id returned by Create Payout. | <mark style="color:$warning;">`120`</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>                               |

### Example Request

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

### Example Response

<mark style="color:$warning;">`200 OK`</mark> — a single payout object (same shape as the items in *Get All Payouts*):

```json
{
  "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": "test@test.com",
  "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 <mark style="color:$warning;">`status`</mark> field to know where the payout is in its lifecycle:

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

**Terminal states:** <mark style="color:$warning;">`processed`</mark>, <mark style="color:$warning;">`failed`</mark>, <mark style="color:$warning;">`rejected`</mark>, <mark style="color:$warning;">`cancelled`</mark> — 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 <mark style="color:$warning;">`sent/processed`</mark> within a few minutes once it’s on-chain. For a <mark style="color:$warning;">`pending-approval`</mark> payout, poll until an admin approves it (then it continues to <mark style="color:$warning;">`sent/processed`</mark>) or rejects it.

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