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

# Create Payouts

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

Create a payout to send funds directly to a recipient’s wallet on the selected blockchain. PayRam validates the request, applies your project’s payout limits, and either queues the payout for sending or holds it for manual approval.

***

### Authentication

This endpoint is **project-API-key only**. Use the API key generated for the project you’re paying out from (Project → API Keys). The payout is created under that key’s project.

### Endpoint

| Item                                            | Value                                                 |
| ----------------------------------------------- | ----------------------------------------------------- |
| <mark style="color:$warning;">`BASE_URL`</mark> | Your PayRam server URL, e.g. `https://yourdomain.com` |
| Method                                          | <mark style="color:$warning;">`POST`</mark>           |

> BASE\_URL: use your plain HTTPS domain (<mark style="color:$warning;">`https://yourdomain.com`</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>                               |

### Request Body

| Field                                                     | Type             | Required   | Description                                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`email`</mark>              | string           | ✅ Yes      | Recipient’s email address (must be a valid email).                                                                                                                                                                                                                                                                    |
| <mark style="color:$warning;">`blockchainCode`</mark>     | string           | ✅ Yes      | Blockchain network. One of <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`BASE`</mark>, <mark style="color:$warning;">`POLYGON`</mark>, <mark style="color:$warning;">`TRX`</mark>.                                                                                                       |
| <mark style="color:$warning;">`currencyCode`</mark>       | string           | ✅ Yes      | Token or native coin to send, e.g. <mark style="color:$warning;">`USDC`</mark>, <mark style="color:$warning;">`USDT`</mark>, <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, <mark style="color:$warning;">`TRX`</mark>. Must be enabled for the project on the chosen chain. |
| <mark style="color:$warning;">`amount`</mark>             | string (decimal) | ✅ Yes      | **Crypto amount** to send, in the currency’s own units — **not USD**. E.g. <mark style="color:$warning;">`"100"`</mark> = 100 USDC. See “Amounts are in crypto” below.                                                                                                                                                |
| <mark style="color:$warning;">`toAddress`</mark>          | string           | ✅ Yes      | Recipient wallet address; must be valid for <mark style="color:$warning;">`blockchainCode`</mark>.                                                                                                                                                                                                                    |
| <mark style="color:$warning;">`customerID`</mark>         | string           | ✅ Yes\*    | Your unique identifier for the recipient in your system. \*Technically optional in the schema, but a payout **cannot be created without it** — omitting it returns an error. Always send it.                                                                                                                          |
| <mark style="color:$warning;">`mobileNumber`</mark>       | string           | ❌ Optional | Recipient’s mobile number.                                                                                                                                                                                                                                                                                            |
| <mark style="color:$warning;">`residentialAddress`</mark> | string           | ❌ Optional | Recipient’s address.                                                                                                                                                                                                                                                                                                  |

### Amounts are in Crypto (not USD)

<mark style="color:$warning;">`amount`</mark> is the exact on-chain amount in the currency’s units (e.g. <mark style="color:$warning;">`"100"`</mark> USDC sends 100 USDC; <mark style="color:$warning;">`"0.05"`</mark> ETH sends 0.05 ETH). PayRam computes the USD value internally for limit checks.

If your system works in fiat, convert USD → crypto **before** creating the payout using the public ticker endpoint, then send the resulting crypto amount:

1. <mark style="color:$warning;">`GET {BASE_URL}/api/v1/ticker`</mark> returns each currency’s live USD <mark style="color:$warning;">`price`</mark> and <mark style="color:$warning;">`walletPrecision`</mark>.
2. <mark style="color:$warning;">`cryptoAmount = usdAmount / price`</mark>, rounded to that currency’s <mark style="color:$warning;">`walletPrecision`</mark>. (Stablecoins have <mark style="color:$warning;">`price = "1.0"`</mark>, so the crypto amount equals the USD amount.)
3. Create the payout with that <mark style="color:$warning;">`amount`</mark>.

> **Native coins are supported.** You can pay out native <mark style="color:$warning;">`ETH`</mark>, <mark style="color:$warning;">`POL`</mark>, and <mark style="color:$warning;">`TRX`</mark> (not only tokens). **BTC is not supported for payouts.**

### Payout Limits and Approval

At creation, PayRam evaluates the payout (in USD) against your project’s limits, **per recipient member within the project**:

* **Auto-approve amount** — payouts at or under this are auto-approved and queued for sending (<mark style="color:$warning;">`status: "pending"`</mark>). Payouts above it require manual approval (<mark style="color:$warning;">`status: "pending-approval"`</mark>).
* **Hourly limit** / **Daily limit** — if the member’s cumulative payouts in this project for the current hour/day would exceed these, the payout is held for approval.
* **Minimum payout** — payouts below this are rejected outright.

When a payout is held, the response <mark style="color:$warning;">`status`</mark> is <mark style="color:$warning;">`pending-approval`</mark> and <mark style="color:$warning;">`attributes.approvalReason`</mark> explains why (<mark style="color:$warning;">`above_auto_approve`</mark>, <mark style="color:$warning;">`daily_limit_exceeded`</mark>, <mark style="color:$warning;">`hourly_limit_exceeded`</mark>, etc.). An admin then approves/rejects it from the dashboard.

> These thresholds are configured per installation and can be overridden per project in the dashboard (**Project → Payout Limits**; the global minimum lives under **Settings → Withdrawal Limits**). Contact PayRam support to change global defaults. Don’t hard-code specific limit values in your integration — read them from your dashboard.

### Example Request

```bash
curl --location '${BASE_URL}/api/v1/withdrawal/merchant' \
--header 'API-Key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "test@test.com",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "amount": "100",
  "toAddress": "0x291b68732f14F47Fd21bE81ec5Cf1bcfC0DB14Ea",
  "customerID": "414817384",
  "mobileNumber": "123456789",
  "residentialAddress": "No 22 OC Street"
}'
```

### Example Response

<mark style="color:$warning;">`201 Created`</mark> — the created payout object:

```json
{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100.000000",
  "toAddress": "0x9F8E7D6C5B4A39281706F5E4D3C2B1A098765432",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "test@test.com",
  "txHash": null,
  "status": "pending-approval",
  "type": "payout_merchant",
  "attributes": "{\"approvalReason\":\"above_auto_approve\"}",
  "externalPlatformID": 1,
  "createdBy": "user"
}
```

<mark style="color:$warning;">`status`</mark> will be:

* <mark style="color:$warning;">**`pending`**</mark> — auto-approved (within limits); queued for sending.
* <mark style="color:$warning;">**`pending-approval`**</mark> — held for manual admin approval (see <mark style="color:$warning;">`attributes.approvalReason`</mark>).

> **The&#x20;**<mark style="color:$warning;">**`id`**</mark>**&#x20;field is important** — it uniquely identifies the payout. Store it; you’ll use it to track status via <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (or find it in the list endpoint).

### Tracking Status

Track status either way:

* **Webhooks (recommended)** — get a <mark style="color:$warning;">`payout.<status>`</mark> event pushed to you on every change (see **Payout Webhooks**).
* **Polling** — <mark style="color:$warning;">`GET /api/v1/withdrawal/{id}/merchant`</mark> (single) or <mark style="color:$warning;">`GET /api/v1/withdrawal/merchant`</mark> (list).

The payout moves through: <mark style="color:$warning;">`pending-approval → pending → initiated → sent → processed`</mark> (<mark style="color:$warning;">`failed`</mark> / <mark style="color:$warning;">`rejected`</mark> are terminal). See the **Status lifecycle** in the Overview.

### Errors

| HTTP | When                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | Missing/invalid required field (<mark style="color:$warning;">`email`</mark> not a valid email, missing <mark style="color:$warning;">`blockchainCode`</mark> / <mark style="color:$warning;">`currencyCode`</mark> / <mark style="color:$warning;">`amount`</mark> / <mark style="color:$warning;">`toAddress`</mark>, invalid wallet address for the chain, or invalid blockchain/currency combination). |
| 400  | <mark style="color:$warning;">`PAYOUT_AMOUNT_BELOW_MINIMUM`</mark> (amount below the project minimum), or <mark style="color:$warning;">`PAYOUT_CURRENCY_DISABLED`</mark> (currency not enabled for payouts).                                                                                                                                                                                              |
| 401  | Missing/invalid <mark style="color:$warning;">`API-Key`</mark>, or a non-project key.                                                                                                                                                                                                                                                                                                                      |
| 500  | <mark style="color:$warning;">`customerID`</mark> omitted (“failed to create customer”), <mark style="color:$warning;">`BTC`</mark> selected (not supported for payouts), or an unexpected server error.                                                                                                                                                                                                   |
| 503  | <mark style="color:$warning;">`EXCHANGE_RATE_UNAVAILABLE`</mark> — a live exchange rate couldn’t be fetched for a non-stablecoin (retryable; try again shortly).                                                                                                                                                                                                                                           |

### Convert USD → Crypto (Ticker)

The Create Payout API takes a **crypto** `amount`, but many systems work in **fiat (USD)**. Use the ticker endpoint to fetch live USD prices, convert your USD amount to the crypto amount, then create the payout. This keeps your conversion aligned with the same pricing PayRam uses internally for its limit checks.

### Endpoint

```
GET {BASE_URL}/api/v1/ticker
```

**Public** — no <mark style="color:$warning;">`API-Key`</mark> required. Returns every currency configured on your server with its current USD price.

### Example Request

```bash
curl --location --request GET '${BASE_URL}/api/v1/ticker'
```

### Example Response

<mark style="color:$warning;">`200 OK`</mark> — an array, one entry per blockchain + currency:

```json
[
  {
    "blockchainCode": "ETH",
    "currencyCode": "ETH",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "standard": "native",
    "walletPrecision": 18,
    "family": "ETH_Family",
    "price": "1659.57"
  },
  {
    "blockchainCode": "BASE",
    "currencyCode": "USDC",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "standard": "ERC20",
    "walletPrecision": 6,
    "family": "ETH_Family",
    "price": "1.0"
  }
]
```

| Field                                                                                                       | Meaning                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:$warning;">`blockchainCode`</mark> / <mark style="color:$warning;">`currencyCode`</mark> | The chain + currency this price applies to.                                                                                                     |
| <mark style="color:$warning;">`price`</mark>                                                                | Current price of **1 unit of the currency in USD** (stablecoins are <mark style="color:$warning;">`"1.0"`</mark>).                              |
| <mark style="color:$warning;">`walletPrecision`</mark>                                                      | Decimal places to round the converted crypto amount to.                                                                                         |
| <mark style="color:$warning;">`tokenAddress`</mark>                                                         | Token contract (<mark style="color:$warning;">`0x000…000`</mark> for native coins).                                                             |
| <mark style="color:$warning;">`standard`</mark>                                                             | <mark style="color:$warning;">`native`</mark>, <mark style="color:$warning;">`ERC20`</mark>, <mark style="color:$warning;">`TRC20`</mark>, etc. |

### How to Convert

For the currency you’re paying out, find the matching row (by `blockchainCode` + `currencyCode`), then:

```
cryptoAmount = usdAmount / price          # rounded to walletPrecision
```

* **Stablecoins** (<mark style="color:$warning;">`price = "1.0"`</mark>) → <mark style="color:$warning;">`cryptoAmount = usdAmount`</mark>.
* **Other currencies** → divide by <mark style="color:$warning;">`price`</mark> and round to <mark style="color:$warning;">`walletPrecision`</mark>.

**Example:** pay out **$50 in ETH** when <mark style="color:$warning;">`price = "1659.57"`</mark>:\ <mark style="color:$warning;">`50 / 1659.57 = 0.030128…`</mark> → rounded to 18 dp → <mark style="color:$warning;">`amount: "0.030128..."`</mark>.

#### Recommended flow

1. Your back office validates the **USD** amount (your own rules).
2. <mark style="color:$warning;">`GET /api/v1/ticker`</mark> → look up the target currency’s <mark style="color:$warning;">`price`</mark> and <mark style="color:$warning;">`walletPrecision`</mark>.
3. Convert USD → crypto and round to <mark style="color:$warning;">`walletPrecision`</mark>.
4. <mark style="color:$warning;">`POST /api/v1/withdrawal/merchant`</mark> with the resulting crypto <mark style="color:$warning;">`amount`</mark>.

> Fetch the ticker **right before** creating the payout so the rate is current. Rounding to <mark style="color:$warning;">`walletPrecision`</mark> avoids “fractional base unit” rejections on create.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payram.com/api-integration/payouts-apis/create-payouts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.