مستندات API رمزفا

شروع سریع

فلو استاندارد ساده است: با API Key در هدر x-api-key یک Access Token بگیرید و سپس همه درخواست‌ها را با Bearer Token بفرستید.

curl -X POST https://api.ramzfa.com/api/public/auth/token \
  -H "Content-Type: application/json" \
  -H "x-api-key: cpay_live_YOUR_KEY" \
  -d '{}'

# سپس با توکن دریافتی:
curl -X POST https://api.ramzfa.com/api/public/invoices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "amount": 10.00,
    "description": "خرید اشتراک",
    "payableCurrencies": ["USDT", "TRX"],
    "payableNetworks": ["TRC20", "BEP20", "TRX"]
  }'

احراز هویت

برای استفاده از API عمومی نیازی به دامنه مرچنت یا تنظیمات اضافی ندارید. فقط API Key کافی است. با آن توکن کوتاه‌مدت می‌گیرید و بعد از آن تمام عملیات مثل ایجاد فاکتور، مدیریت فاکتور، تاریخچه و موجودی با Bearer Token انجام می‌شود.

ایجاد فاکتور

درخواست ایجاد فاکتور را به POST /api/public/invoices بفرستید. در صورت نیاز می‌توانید URLهای موفق، لغو و callback را همان‌جا تعیین کنید.

{
  "amount": 10.00,
  "description": "خرید اشتراک ماهانه",
  "payableCurrencies": ["USDT", "TRX"],
  "payableNetworks": ["TRC20", "BEP20"],
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "metadata": {
    "orderId": "ORD-12345",
    "userId": "user_abc"
  }
}

مدیریت مشتری

با endpoint /api/public/customer-wallets برای هر مشتری یک آدرس استاتیک دائمی بسازید با شناسه موبایل، ایمیل یا Telegram ID. صفحه عمومی مشتری با بارکد، تاریخچه و ایجاد فاکتور خودکار تولید می‌شود.

Webhook

رمزفا رویدادها را به URL تعریف‌شده شما ارسال می‌کند. رویدادهای اصلی: payment.confirmed, payment.underpaid, payment.overpaid.

// دریافت ساده رویداد در Express.js
app.post('/webhook', (req, res) => {
  if (req.body.event === 'payment.confirmed') {
    const invoice = req.body.invoice;
    // فاکتور تایید شد — سفارش را فعال کنید
    fulfillOrder(invoice.metadata.orderId);
  }
  res.json({ received: true });
});