Send crypto payouts and manage referral programs with PayRam. Self-hosted payout infrastructure — no KYC, no intermediary, no fund holds. Create payouts to any wallet across Ethereum, Base, Polygon, Tron, Bitcoin. Built-in affiliate program with automated reward distribution. Use when sending crypto payouts to users, building referral/affiliate programs, or needing integrated payment and payout infrastructure.
Send crypto payouts and manage referral programs with PayRam. Self-hosted payout infrastructure — no KYC, no intermediary, no fund holds. Create payouts to any wallet across Ethereum, Base, Polygon, Tron, Bitcoin. Built-in affiliate program with automated reward distribution. Use when sending crypto payouts to users, building referral/affiliate programs, or needing integrated payment and payout infrastructure.
PayRam Payouts & Referrals
First time with PayRam? See payram-setup to configure your server, API keys, and wallets.
PayRam uniquely combines inbound payments with outbound payouts and built-in referral tracking—a complete payment + growth stack in one self-hosted platform.
Why This Matters
Most payment processors handle only inbound. Payouts require separate integrations (Wise, PayPal, manual transfers). Referral tracking needs yet another tool (FirstPromoter, Rewardful).
PayRam offers two payout flows (see merchant-payouts-api.md in payram-core for the full contract):
Flow
When to use
OTP?
Endpoints
Saved recipient (recommended)
Repeat payments to the same beneficiary; you want an OTP-verified audit trail
Yes (once per recipient)
POST /api/v1/recipients → POST /api/v1/otp/validate → POST /api/v1/project/{projectID}/admin/withdrawal
Direct (single-shot)
One-off payouts (refunds, ad-hoc disbursements)
No
POST /api/v1/withdrawal/merchant
Both flows authenticate with the API-Key header (a Merchant API key scoped to one project) — never Authorization: Bearer.
Saved Recipient Flow (recommended) — 3 steps
A recipient is a destination address + identity metadata, OTP-verified once and reused for any number of payouts. The JS SDK has no recipient/OTP methods, so call these REST endpoints directly.
constHOST = process.env.PAYRAM_BASE_URL!.replace(/\/+$/, '');
constPROJECT_ID = Number(process.env.PAYRAM_PROJECT_ID);
const headers = { 'API-Key': process.env.PAYRAM_API_KEY!, 'Content-Type': 'application/json' };
asyncfunction call<T>(method: string, path: string, body?: unknown): Promise<T> {
const res = awaitfetch(`${HOST}/api/v1${path}`, {
method,
headers,
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) thrownewError(`Payram ${method}${path}: ${res.status}${await res.text()}`);
return res.json() asPromise<T>;
}
// 1) Create recipient → status "pending-otp-verification"; PayRam emails a 6-digit OTP// to the API-key owner's address (10-min validity).const { recipient } = await call<{ recipient: { id: number; status: string } }>(
'POST',
'/recipients',
{
name: 'Acme Supplier Ltd',
email: 'supplier@acme.example',
blockchainCode: 'ethereum', // lowercase chain name: ethereum | bitcoin | tron | base | polygonaddress: '0xAbCdEf0123456789AbCdEf0123456789AbCdEf01',
projectIDs: [PROJECT_ID], // required, min 1
},
);
// 2) Validate the OTP from the operator inbox → recipient becomes "active".// Expired? POST /otp/entity/{recipient.id}/purpose/recipient to regenerate.awaitcall('POST', '/otp/validate', {
entityID: recipient.id,
scope: 'recipient', // literal stringotpCode: '482913', // read from the email
});
// 3) Create the payout against the active recipient.const withdrawal = await call<{ id: number; status: string }>(
'POST',
`/project/${PROJECT_ID}/admin/withdrawal`,
{
currencyCode: 'ETH', // uppercase ticker: ETH | BTC | USDC | USDT | POL | TRX | CBBTCamount: '0.05', // decimal stringrecipientID: recipient.id, // must be "active"
},
);
Required API-key permissions:write_recipient, read_recipient, write_validate_otp, write_merchant_withdrawal (missing one → 403). The OTP is not returned by the API (otpSent: true only) — plan a human or inbox-reading step. Recipients are project-scoped; a recipient created for project A cannot be paid against project B.
CREATE TABLE payouts (
id SERIAL PRIMARY KEY,
payram_payout_id INTEGERUNIQUENOT NULL,
customer_id VARCHAR(255) NOT NULL,
blockchain_code VARCHAR(50) NOT NULL,
currency_code VARCHAR(50) NOT NULL,
amount DECIMAL(20, 8) NOT NULL,
to_address VARCHAR(255) NOT NULL,
status VARCHAR(50) NOT NULL,
transaction_hash VARCHAR(255),
created_at TIMESTAMPDEFAULT NOW(),
updated_at TIMESTAMPDEFAULT NOW()
);
