> 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="https://3861722996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fwm1DIvbGMREWT1TdLPtz%2Fuploads%2FTh2uijiaNvL6SpgUdQPj%2Fpayram-payout-overview.png?alt=media&amp;token=e0af03f8-84a6-42a2-990d-86379c5047f8" 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

Every endpoint is called as `{BASE_URL}/api/v1/...`. Your `BASE_URL` is the address your PayRam instance is reachable at — the same one you open the dashboard with.

{% stepper %}
{% step %}

### Open your PayRam dashboard

Log in to your PayRam dashboard as usual.
{% endstep %}

{% step %}

### Go to Settings

Select **Settings** from the left menu.
{% endstep %}

{% step %}

### Open Site URL

Select **Site URL**. The address shown under **Current site URL** is your `BASE_URL`.
{% endstep %}
{% endstepper %}

| Your setup                    | BASE\_URL                 |
| ----------------------------- | ------------------------- |
| Domain with SSL               | `https://pay.example.com` |
| Server IP, no SSL             | `http://192.168.0.1`      |
| Installed on a different port | `http://192.168.0.1:3000` |

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: PayRam serves the dashboard and the API from the same address, so there is no separate API port. If you installed on a port other than the default, include it in your</mark> <mark style="color:$warning;">`BASE_URL`</mark><mark style="color:$info;">.</mark>
{% endhint %}

### 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`.

Idempotency keys on payout creation require **PayRam v3.6.0 or later**. On older versions the key is ignored.

### 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

| Network      | <mark style="color:$warning;">`blockchainCode`</mark> | Native coin                                | Tokens                                                                                                                                                                               |
| ------------ | ----------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ethereum** | <mark style="color:$warning;">`ETH`</mark>            | <mark style="color:$warning;">`ETH`</mark> | <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>, <mark style="color:$warning;">`PYUSD`</mark>, <mark style="color:$warning;">`CBBTC`</mark> |
| **Base**     | <mark style="color:$warning;">`BASE`</mark>           | <mark style="color:$warning;">`ETH`</mark> | <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`CBBTC`</mark>                                                                                            |
| **Polygon**  | <mark style="color:$warning;">`POLYGON`</mark>        | <mark style="color:$warning;">`POL`</mark> | <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>                                                                                             |
| **Tron**     | <mark style="color:$warning;">`TRX`</mark>            | <mark style="color:$warning;">`TRX`</mark> | <mark style="color:$warning;">`USDT`</mark>                                                                                                                                          |
| **Bitcoin**  | —                                                     | —                                          | **Not supported for payouts**                                                                                                                                                        |

{% hint style="info" %} <mark style="color:$primary;">**Note**</mark><mark style="color:$info;">: A currency can be paid out only when it is enabled for your project on that chain and the project has a hot wallet for that network. See</mark> [<mark style="color:$info;">Hot Wallet Setup</mark>](/onboarding-guide/hot-wallet-setup.md)<mark style="color:$info;">.</mark>
{% endhint %}

### 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.