🌟Create Payouts

In this section, you’ll learn how to create a payout in PayRam to send funds directly to a recipient’s wallet on the selected blockchain.

Create an API payout. PayRam checks it against your project’s limits and either queues it to send (pending) or holds it for approval (pending-approval).

Before you start: the project needs a hot wallet assigned for the payout’s network (Hot Wallet Setup), otherwise the request fails with 422 PAYOUT_HOT_WALLET_NOT_ASSIGNED (PayRam Core v3.9.0 and later).

---

Endpoint

POST {BASE_URL}/api/v1/withdrawal/merchant

Header	Required	Value
API-Key	Yes	Your project API key
Content-Type	Yes	application/json
Idempotency-Key	No	Up to 255 characters, e.g. payout-00417. See Idempotency.

Request body

Field	Type	Required	Description
email	string	Yes	Recipient’s email (must be a valid email).
blockchainCode	string	Yes	ETH, BASE, POLYGON or TRX.
currencyCode	string	Yes	Token or native coin, e.g. USDC, USDT, ETH, POL, TRX. See Supported networks.
amount	string	Yes	Amount in the token, not USD — e.g. "100" USDC or "0.05" ETH. See Amounts.
toAddress	string	Yes	Recipient wallet; must be valid for blockchainCode.
customerID	string	Yes	Your identifier for the recipient. A payout cannot be created without it.
mobileNumber	string	No	Recipient’s mobile number.
residentialAddress	string	No	Recipient’s address.
idempotencyKey	string	No	Same as the Idempotency-Key header; the header wins if both are sent.

Amounts

• amount is in the token’s own units. To pay a USD value, convert it first with the ticker.

• PayRam truncates the amount to the token’s precision (walletPrecision) — never rounds up and never rejects for extra decimals. An amount that truncates to zero is rejected. Round it yourself so your records match what is sent.

• Bitcoin payouts are not supported: they are refused at creation with 400 PAYOUT_CURRENCY_DISABLED (PayRam Core v3.9.0 and later).

Limits and approval

Limits are evaluated in USD over rolling windows: the last 60 minutes and the last 24 hours. The totals count what the same account has paid out in the project: the API key’s account for API payouts. Payouts held for approval count toward those totals; failed, rejected and cancelled ones do not.

Outcome	Result
Within limits	201, status: "pending" — queued to send.
Over the auto-approve amount, or over a limit	201, status: "pending-approval" with approvalReason in attributes.
Below the minimum	400 PAYOUT_AMOUNT_BELOW_MINIMUM — no payout is created.

Limits are set in the dashboard — see Editing Payout Limits. Don’t hard-code them.

Idempotency

Always send an idempotency key. Without one, PayRam cannot tell a retry after a timeout from a deliberate second payout.

• Generate one key per payout before the first attempt and store it with the payout (an order ID works; a timestamp does not).

• Retrying with the same key returns the original payout with 201 and the header Idempotent-Replayed: true (PayRam Core v3.9.0 and later). Keys are per project and do not expire.

• A reused key with a different body still returns the original payout — never reuse a key for a different payout.

• Without a key, an identical payout (same project, address, token, network and amount) within 5 minutes is refused with 409 PAYOUT_DUPLICATE_REQUEST.

---

Example request

curl --location '${BASE_URL}/api/v1/withdrawal/merchant' \
--header 'API-Key: <API_KEY>' \
--header 'Idempotency-Key: payout-00417' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "[e-mail]",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "amount": "100",
  "toAddress": "0x291b68732f14F47Fd21bE81ec5Cf1bcfC0DB14Ea",
  "customerID": "414817384"
}'

Example response

201 Created:

{
  "id": 120,
  "createdAt": "2026-06-19T13:14:41.806Z",
  "blockchainCode": "ETH",
  "currencyCode": "USDC",
  "currencyType": "token",
  "amount": "100",
  "priceInUSD": "1",
  "amountInUSD": "100",
  "toAddress": "0x291b68732f14F47Fd21bE81ec5Cf1bcfC0DB14Ea",
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "recipientEmail": "[e-mail]",
  "txHash": null,
  "status": "pending-approval",
  "type": "payout_merchant",
  "attributes": "{\"approvalReason\":\"above_auto_approve\"}",
  "createdBy": "user"
}

Store the id — you need it to look up the payout. Field meanings are in GET All Payouts.

Errors

API errors use this shape:

{"error": {"code": "PAYOUT_DUPLICATE_REQUEST", "message": "...", "details": "..."}}

Only an error worth retrying (for example EXCHANGE_RATE_UNAVAILABLE) also carries "retryable": true; otherwise the field is absent.

A body that fails validation (missing field, invalid email) returns 400 with a different shape; fields maps each field to its problem. Malformed JSON (including a non-numeric amount) returns 400 with "error": "Invalid JSON" and no fields.

{"error": "Validation failed", "message": "Invalid request data", "fields": {"Email": "Email must be a valid email address"}}

HTTP	code	When
400	BAD_REQUEST	Amount zero, negative, too large, or below the token’s smallest unit; address invalid for the network; unknown network or token code; missing customerID (PayRam Core v3.9.0 and later). Idempotency-Key over 255 characters.
400	PAYOUT_CURRENCY_DISABLED	Payouts are turned off for this token, or it is Bitcoin. (PayRam Core v3.9.0 and later)
400	PAYOUT_AMOUNT_BELOW_MINIMUM	Amount is below the project minimum.
401	UNAUTHORIZED	Missing or invalid API-Key, or not a project key.
403	INSUFFICIENT_PERMISSIONS	The key lacks payout permission.
404	NOT_FOUND	This network + token pair is not configured on the server.
409	PAYOUT_DUPLICATE_REQUEST	Identical payout within 5 minutes and no idempotency key.
422	PAYOUT_HOT_WALLET_NOT_ASSIGNED	No hot wallet assigned to the project for this network. (PayRam Core v3.9.0 and later)
503	EXCHANGE_RATE_UNAVAILABLE	No live price for a non-stablecoin. Retryable; sent with Retry-After: 30.
500	INTERNAL_SERVER_ERROR	Anything else.

Retry rule: treat 4xx as permanent — fix the request, don’t retry it. Retry 5xx (including EXCHANGE_RATE_UNAVAILABLE), always with the same idempotency key.

---

Convert USD to crypto (ticker)

GET {BASE_URL}/api/v1/ticker

Public — no API-Key. Returns one entry per network + currency:

[
  {
    "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
blockchainCode / currencyCode	The network + currency the price applies to.
price	USD price of 1 unit (stablecoins are "1.0").
walletPrecision	Decimal places the token supports — round to this.
tokenAddress	Token contract (0x000…000 for native coins).
standard	native, ERC20, TRC20, etc.

Convert: amount = usdAmount / price, rounded down to walletPrecision. Example: $50 in ETH at price = "1659.57" → 0.030128…. Fetch the ticker right before creating the payout so the rate is current.