API Documentation مستندات فنی وب‌سرویس

Welcome to the Crypto Payment Gateway developer reference. Our API is structured as a self-hosted, merchant-authenticated gateway utilizing the PayGate.to integration. You can create invoices in fiat (USD) and automatically receive payments in cryptocurrency.

به مستندات فنی درگاه پرداخت کریپتو خوش آمدید. وب‌سرویس ما یک درگاه پرداخت غیرمتمرکز، امن و مبتنی بر وب‌هووک است که به پذیرندگان اجازه می‌دهد فاکتورها را به دلار ایجاد کرده و پرداخت‌ها را به صورت کریپتوکارنسی دریافت کنند.

Authentication احراز هویت

All requests to protected API endpoints require an API Key supplied in the HTTP headers. You can generate API Keys from your gateway Admin Dashboard.

تمامی درخواست‌ها به متدهای سیستمی درگاه به کلید احراز هویت (API Key) نیاز دارند که باید در هدرهای HTTP درخواست شما ارسال گردد. این کلیدها از پنل مدیریت قابل دریافت هستند.

X-API-Key: mw_your_merchant_api_key

Create Invoice ایجاد فاکتور جدید

Initialize a checkout invoice session for a client. You supply the fiat USD amount, callback URL, and return URL. The API will respond with a unique checkout_url that you should redirect the user to.

برای شروع چرخه پرداخت مشتری، یک فاکتور جدید ثبت کنید. شما مبلغ فاکتور به دلار، آدرس بازگشت خریدار و آدرس وب‌هووک تاییدیه را ارسال می‌کنید و درگاه یک لینک یکتای checkout_url به شما باز می‌گرداند که باید کاربر را به آن هدایت کنید.

HTTP Request: POST /api/v1/invoices

Request Parameters:

پارامترهای ارسالی:

Sample JSON Request:

نمونه بدنه درخواست (JSON):

{
    "amount_usd": 15.50,
    "callback_url": "https://mystore.com/api/payment-callback?order_id=7492",
    "redirect_url": "https://mystore.com/checkout/success"
}

Get Invoice Details دریافت جزئیات فاکتور

Retrieve details of a generated invoice. This is a public endpoint used to fetch transaction status, selected crypto coin, crypto amount, and address details.

دریافت جزئیات فاکتور ایجاد شده. این متد عمومی است و نیازی به توکن احراز هویت ندارد و برای استعلام وضعیت پرداخت، رمزارز انتخاب شده، مقدار معادل رمزارز و آدرس کیف پول پرداخت استفاده می‌شود.

HTTP Request: GET /api/v1/public/invoices/{invoice_id}

Callback Notifications (Webhooks) کال‌بک‌های وب‌هووک (ارسال خودکار وضعیت)

When an invoice transitions to a final status (such as `paid`, `partially_paid`, or `expired`), the gateway issues a POST callback request to the `callback_url` configured during initialization.

وقتی وضعیت فاکتور به حالت نهایی تغییر کند (مانند `paid` یا `expired` یا `partially_paid`)، درگاه پرداخت یک درخواست POST به صورت سرور-به-سرور به آدرس `callback_url` پذیرنده ارسال می‌کند.

Webhook Headers:

هدرهای ارسالی وب‌هووک:

Content-Type: application/json
X-Gateway-Signature: computed_hmac_sha256_hash

Webhook JSON Payload:

نمونه داده وب‌هووک ارسالی:

{
    "invoice_id": "019ec14f-6034-7323-ac1d-6b11769b6e30",
    "amount_usd": 15.50,
    "currency": "USDT",
    "network": "TRC-20",
    "crypto_amount": 15.50,
    "payment_address": "TUPD6kRECdwQK6eH2P1igx1nR4ofmsYH6Y",
    "status": "paid",
    "tx_hash": "63f82a938ea12d8a4d87...",
    "timestamp": 1781362800
}

Webhook Signature Verification اعتبارسنجی امضای وب‌هووک

To protect your application from fraudulent webhooks, calculate the HMAC SHA-256 signature of the raw request payload using your **API Secret** key and compare it with the `X-Gateway-Signature` header. Use timing-attack safe comparison.

برای محافظت از سرور خود در برابر وب‌هووک‌های جعلی، باید امضای دیجیتال هدر `X-Gateway-Signature` را اعتبارسنجی کنید. برای این کار بدنه خام درخواست دریافتی را با استفاده از **API Secret** خود هش کرده و مقایسه امن انجام دهید.

PHP Signature Example:

نمونه اعتبارسنجی در PHP:

$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '';
$apiSecret = "ms_your_api_secret_key";

$expectedSignature = hash_hmac('sha256', $payload, $apiSecret);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Valid webhook - process status / امضا معتبر است، فاکتور را پردازش کنید
    http_response_code(200);
    echo "OK";
} else {
    // Verification failed / امضا نامعتبر است
    http_response_code(400);
    die("Invalid Signature");
}