📘Overview

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
API-Key	Yes	Your project API key, e.g. be703fa47ebe07121102ee260fb3d5c0
Content-Type	Yes	application/json

Approve / Reject are done from the dashboard.

Version requirement

The merchant payout endpoints (/withdrawal/merchant, /withdrawal/{id}/merchant) require PayRam v3.1.1 or later. On older versions they return 404.

Endpoints at a glance

Method	Path	Purpose
POST	/api/v1/withdrawal/merchant	Create a payout
GET	/api/v1/withdrawal/{id}/merchant	Get one payout / check its status
GET	/api/v1/ticker	Live USD prices (for USD → crypto conversion)
GET	/api/v1/withdrawal/merchant	List your project’s payouts

Amounts are in crypto

The payout amount is the crypto amount in the currency’s own units (e.g. "100" USDC = 100 USDC; "0.05" 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: ETH, BASE, POLYGON (EVM), and TRX.

• Currencies: tokens (e.g. USDC, USDT) and native coins (ETH, POL, TRX), as enabled for your project on each chain.

• BTC is not supported for payouts.

Status lifecycle

Every payout reports a status:

Status	Meaning
pending-otp-verification	Waiting for OTP verification before processing.
pending-approval	Held for manual approval — exceeded the auto-approve amount or an hourly/daily limit (attributes.approvalReason says which).
pending	Approved (or auto-approved) and queued for on-chain processing.
initiated	Broadcast to the blockchain (txHash set); awaiting confirmation.
sent	Transaction confirmed on-chain.
processed	Confirmed and recorded in accounting — fully complete.
failed	Processing failed — see failureReason.
rejected	Declined by an admin (or the system).
cancelled	Intentionally stopped before being sent/processed.

Terminal states: processed, failed, rejected, cancelled.

Tracking payouts

Two ways to track a payout to completion:

• Webhooks (recommended) — PayRam POSTs a payout.<status> event to your registered webhook URL on every status change. See Payout Webhooks at the end of this doc.

• Polling — GET /api/v1/withdrawal/{id}/merchant (or the list endpoint) until the payout reaches a terminal state.