مستندات توسعه‌دهندگان

با استفاده از API قدرتمند ما، می‌توانید درگاه پرداخت ارز دیجیتال (بیت‌کوین، ترون، تتر و...) را در کمتر از ۱۰ دقیقه به وب‌سایت یا اپلیکیشن خود متصل کنید.

نکته مهم: تمامی درخواست‌ها باید به آدرس پایه (Base URL) زیر ارسال شوند. لطفاً از هدرهای استاندارد HTTP استفاده کنید.

Base URL

احراز هویت

در نسخه فعلی (v1.0)، API به صورت عمومی (Public) طراحی شده است تا فرآیند ادغام سریع‌تر انجام شود. امنیت تراکنش‌ها از طریق مکانیزم‌های زیر تامین می‌شود:

استفاده از order_id یکتا برای هر تراکنش.
تولید آدرس کیف پول اختصاصی برای هر سفارش.
تایید صحت تراکنش در بلاکچین قبل از فراخوانی Webhook.

ارزهای پشتیبانی شده

لیست ارزهایی که می‌توانید در پارامتر currency استفاده کنید (حروف کوچک یا بزرگ فرقی ندارد):

نام ارز	نماد (Symbol)	شبکه (Network)
Bitcoin	`btc`	Bitcoin Mainnet
Tron	`trx`	Tron Mainnet
Litecoin	`ltc`	Litecoin
Dogecoin	`doge`	Dogecoin
Bitcoin Cash	`bch`	BCH
DigiByte	`dgb`	DigiByte
BNB	`bnb`	BSC (BEP-20)
Ethereum	`eth`	ERC-20
Polygon	`matic`	Polygon
Dash	`dash`	Dash
Zcash	`zec`	Zcash
Fantom	`ftm`	Fantom Opera
Avalanche	`avax`	C-Chain
Toncoin	`ton`	TON (Wallet V4R2)

حداقل مقدار قابل‌قبول واریز برای هر ارز، در پنل مدیریت قابل تنظیم است و ممکن است تغییر کند؛ اگر واریزی کمتر از حداقل باشد، تراکنش تا رسیدن به آستانه در وضعیت pending باقی می‌ماند.

POST

ایجاد پرداخت

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

پارامترهای درخواست

نام پارامتر	نوع	وضعیت	توضیحات
`action`	String	الزامی	مقدار ثابت `create` (معمولاً در Query String).
`amount`	Number	الزامی	مبلغ سفارش بر پایه دلار (USD). سیستم به صورت خودکار تبدیل ارز را انجام می‌دهد.
`currency`	String	الزامی	کد ارز دیجیتال (مثال: `trx`, `ton`).
`order_id`	String	اختیاری	شناسه‌ی سفارش در سیستم شما. اگر ارسال نشود، یک شناسه‌ی امن و تصادفی به‌صورت خودکار ساخته می‌شود.
`callback_url`	String	اختیاری	آدرس دریافت وب‌هوک برای این سفارش مشخص. باید `http` یا `https` باشد و به شبکه‌ی داخلی/لوکال اشاره نکند.

Request Example

$url = 'https://copinex.ir/api.php?action=create';
$payload = [
    'amount'       => 50,          // $50 USD
    'currency'     => 'ton',       // Toncoin
    'order_id'     => 'ORD-9821',  // Your unique ID
    'callback_url' => 'https://yoursite.com/webhook.php'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if (isset($result['status']) && $result['status'] === 'success') {
    // انتقال کاربر به درگاه پرداخت
    header("Location: " . $result['payment_url']);
} else {
    echo "Error: " . ($result['message'] ?? 'Unknown error');
}

const axios = require('axios');

const params = new URLSearchParams();
params.append('amount', '50');
params.append('currency', 'ton');
params.append('order_id', 'ORD-9821');
params.append('callback_url', 'https://yoursite.com/webhook');

axios.post('https://copinex.ir/api.php?action=create', params)
  .then(response => {
    if(response.data.status === 'success') {
        console.log('Redirect User to:', response.data.payment_url);
    }
  })
  .catch(error => console.error(error));

import requests

url = "https://copinex.ir/api.php?action=create"
data = {
    'amount': 50,
    'currency': 'ton',
    'order_id': 'ORD-9821',
    'callback_url': 'https://yoursite.com/webhook'
}

response = requests.post(url, data=data)
result = response.json()

if result.get('status') == 'success':
    print(f"Payment URL: {result['payment_url']}")
else:
    print(f"Error: {result.get('message')}")

نمونه پاسخ موفق (JSON)

Status: 200 OK

{
    "status": "success",
    "order_id": "ORD-9821",
    "amount_usd": 50,
    "amount_crypto": "500.00000000",
    "currency": "ton",
    "wallet_address": "UQ...",
    "expiry_time": 1709230000,
    "payment_url": "https://copinex.ir/invoice.php?id=ORD-9821"
}

GET

بررسی وضعیت تراکنش

در صورتی که Webhook دریافت نکردید، می‌توانید وضعیت سفارش را به صورت دستی استعلام بگیرید.

تغییر امنیتی مهم: ارسال api_key در این متد از این پس الزامی است. بدون آن، دیگر امکان استعلام وضعیت هیچ سفارشی وجود ندارد — این تغییر برای جلوگیری از دسترسی افراد غیرمجاز به اطلاعات سفارش‌های سایر کاربران (مثل مبلغ و tx_hash) اعمال شده است.

Endpoint

پارامترهای درخواست

نام پارامتر	وضعیت	توضیحات
`id` یا `order_id`	الزامی	شناسه‌ی سفارشی که هنگام ایجاد پرداخت دریافت کردید.
`api_key`	الزامی	کلید API شما؛ فقط سفارش‌های متعلق به همین کلید قابل مشاهده هستند.

پاسخ JSON

{
    "status": "success",
    "data": {
        "order_id": "ORD-9f1a2b3c...",
        "status": "confirmed",    // pending, confirmed, expired
        "tx_hash": "a1b2c3d4...", // هش تراکنش در بلاکچین (در صورت وجود)
        "amount_crypto": "500.00000000",
        "amount_usd": "12.34",
        "currency": "trx"
    }
}

خطاهای احتمالی

{ "status": "error", "message": "API Key is required" }
{ "status": "error", "message": "Order not found" }

وب‌هوک (Webhook)

توجه: سرور شما باید همیشه آماده دریافت درخواست از سمت ما باشد. ما نتیجه‌ی پرداخت را به‌صورت درخواست POST با بدنه‌ی JSON (نه Query String) به callback_url شما ارسال می‌کنیم.

به‌خاطر امنیت (جلوگیری از SSRF)، آدرس callback_url باید http یا https باشد و نباید به آدرس‌های داخلی/لوکال (مثل 127.0.0.1 یا شبکه‌های خصوصی) اشاره کند؛ در غیر این‌صورت هنگام ثبت رد می‌شود.

ساختار بدنه‌ی درخواست (JSON Body)

نمونه‌ی هدر درخواست: Content-Type: application/json — بسته به این‌که واریز اول سفارش است یا مبلغ اضافی روی همان آدرس، فیلد additional_amount ممکن است وجود نداشته باشد.

{
    "order_id": "ORD-9f1a2b3c...",
    "status": "confirmed",
    "amount": 500.0,
    "currency": "TRX",
    "address": "TXyz...abc"
}

فیلد	توضیحات
`order_id`	همان شناسه سفارشی که هنگام ایجاد پرداخت دریافت کردید.
`status`	`confirmed`: پرداخت (یا واریز اضافی) تایید شد.
`amount`	مجموع مقدار دریافتی به همان ارز دیجیتال، تا لحظه‌ی ارسال این وب‌هوک.
`additional_amount`	فقط در صورت واریز مازاد روی یک آدرس از‌قبل‌تایید‌شده ارسال می‌شود: مقدار فقط همین واریز جدید.
`currency`	نماد ارز دیجیتال (حروف بزرگ، مثل `TRX`).
`address`	آدرس کیف پول اختصاصی این سفارش.

چون تحویل وب‌هوک تضمین‌شده نیست (مثلاً اگر سرور شما موقتاً پایین باشد)، همیشه به‌صورت مکمل از متد بررسی وضعیت هم برای اطمینان نهایی استفاده کنید.

تغییرات اخیر API

Breaking متد check_status از این پس نیازمند پارامتر api_key است. درخواست‌های بدون این پارامتر با خطا مواجه می‌شوند.
تغییر فرمت خودکار order_id (زمانی که ارسال نمی‌کنید) از الگوی قابل‌پیش‌بینی ORD-{timestamp}{rand} به یک شناسه‌ی تصادفی و امن تغییر کرده است. اگر منطق سمت شما به فرمت قبلی وابسته بود (مثلاً parse کردن timestamp از داخل order_id)، لازم است به‌روزرسانی شود.
افزوده شد پشتیبانی از ton (Toncoin، استاندارد Wallet V4R2) به لیست ارزهای فعال اضافه شد.

کدهای خطا

در صورت بروز خطا، فیلد status برابر با error خواهد بود و فیلد message توضیحات را نمایش می‌دهد.

کد خطا	پیام (Message)	علت
`400`	Invalid Action	پارامتر action ارسال نشده یا اشتباه است.
`401`	Amount Required	مبلغ وارد نشده است.
`402`	Invalid Currency	ارز انتخاب شده پشتیبانی نمی‌شود.
`403`	Min Amount Error	مبلغ کمتر از حداقل مجاز برای این ارز است.
`500`	System Error	خطای داخلی سرور یا درگاه.

کتابخانه PHP

کلاس آماده PHP برای اتصال سریع و استاندارد به درگاه.

راهنمای استفاده

فایل دانلود شده را در پروژه خود قرار دهید (مثلا CryptoGateway.php) و به صورت زیر استفاده کنید:

require_once 'CryptoGateway.php';

// 1. تنظیمات اولیه
$gateway = new CryptoGateway('https://copinex.ir/api.php');

// 2. ایجاد فاکتور
$result = $gateway->createPayment(50, 'trx', 'ORD-123', 'https://site.com/callback');

if ($result['status'] === 'success') {
    header("Location: " . $result['payment_url']);
} else {
    echo "Error: " . $result['message'];
}