> 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/overview.md).

# Overview

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

Send funds from your project to a recipient’s wallet, and track each payout to completion. This reference covers creating payouts, checking status, approving/rejecting payouts that are held for review, listing them, and receiving status updates via webhooks.

***

### Base URL

Use your PayRam server’s HTTPS domain:

```
<https://yourdomain.com>
```

### Authentication

Every request authenticates with a **project API key** sent in the `API-Key` header. Generate one per project from the dashboard (**Project → API Keys**). All reads and creates are automatically **scoped to that key’s project** — you only ever see or act on your own project’s payouts.

| Header                                              | Required | Value                                                                                              |
| --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`API-Key`</mark>      | Yes      | Your project API key, e.g. <mark style="color:$warning;">`be703fa47ebe07121102ee260fb3d5c0`</mark> |
| <mark style="color:$warning;">`Content-Type`</mark> | Yes      | <mark style="color:$warning;">`application/json`</mark>                                            |

> **Approve / Reject** are done from the dashboard.

### Version requirement

The merchant payout endpoints (<mark style="color:$warning;">`/withdrawal/merchant`</mark>, <mark style="color:$warning;">`/withdrawal/{id}/merchant`</mark>) require **PayRam v3.1.1 or later**. On older versions they return `404`.

### Endpoints at a glance

| Method                                      | Path                                                                    | Purpose                                       |
| ------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| <mark style="color:$warning;">`POST`</mark> | <mark style="color:$warning;">`/api/v1/withdrawal/merchant`</mark>      | Create a payout                               |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/withdrawal/{id}/merchant`</mark> | Get one payout / check its status             |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/ticker`</mark>                   | Live USD prices (for USD → crypto conversion) |
| <mark style="color:$warning;">`GET`</mark>  | <mark style="color:$warning;">`/api/v1/withdrawal/merchant`</mark>      | List your project’s payouts                   |

### Amounts are in crypto

The payout <mark style="color:$warning;">`amount`</mark> is the **crypto amount** in the currency’s own units (e.g. <mark style="color:$warning;">`"100"`</mark> USDC = 100 USDC; <mark style="color:$warning;">`"0.05"`</mark> ETH = 0.05 ETH) — **not USD**. If your system works in fiat, convert USD → crypto first using the ticker (see **Convert USD → Crypto**).

### Supported networks & currencies

* **Networks:** <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`BASE`</mark>, <mark style="color:$warning;">`POLYGON`</mark> (EVM), and <mark style="color:$warning;">`TRX`</mark>.
* **Currencies:** tokens (e.g. <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>) and native coins (<mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, <mark style="color:$warning;">`TRX`</mark>), as enabled for your project on each chain.
* **BTC is not supported for payouts.**

### Status lifecycle

Every payout reports a <mark style="color:$warning;">`status`</mark>:

| 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 — exceeded the auto-approve amount or an hourly/daily limit (<mark style="color:$warning;">`attributes.approvalReason`</mark> says which). |
| <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> set); awaiting confirmation.                                                             |
| <mark style="color:$warning;">`sent`</mark>                     | Transaction confirmed on-chain.                                                                                                                                     |
| <mark style="color:$warning;">`processed`</mark>                | Confirmed and recorded in accounting — fully complete.                                                                                                              |
| <mark style="color:$warning;">`failed`</mark>                   | Processing failed — see <mark style="color:$warning;">`failureReason`</mark>.                                                                                       |
| <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>.

### Tracking payouts

Two ways to track a payout to completion:

* **Webhooks (recommended)** — PayRam POSTs a <mark style="color:$warning;">`payout.<status>`</mark> event to your registered webhook URL on every status change. See **Payout Webhooks** at the end of this doc.
* **Polling** — <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (or the list endpoint) until the payout reaches a terminal state.