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

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

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

Base URL

احراز هویت

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

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

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

لیست ارزهایی که می‌توانید در پارامتر currency استفاده کنید:

نام ارز	نماد (Symbol)	شبکه (Network)	حداقل مقدار
Bitcoin	`btc`	Bitcoin Mainnet	0.0001 BTC
Tron	`trx`	TRC20	10 TRX
Tether	`usdt`	TRC20	1 USDT
Litecoin	`ltc`	Litecoin	0.01 LTC
Dogecoin	`doge`	Dogecoin	10 DOGE

POST

ایجاد پرداخت

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

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

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

Request Example

$url = 'https://copinex.ir/api.php?action=create';
$payload = [
    'amount'       => 50,          // $50 USD
    'currency'     => 'trx',       // Tron
    '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', 'trx');
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': 'trx',
    '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": "trx",
    "wallet_address": "TMx...",
    "expiry_time": 1709230000,
    "payment_url": "https://copinex.ir/invoice.php?id=ORD-9821"
}

GET

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

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

Endpoint

پاسخ JSON

{
    "status": "success",
    "data": {
        "status": "confirmed",    // pending, confirmed, expired, canceled
        "tx_hash": "a1b2c3d4...", // هش تراکنش در بلاکچین
        "amount_crypto": "500.00000000",
        "currency": "trx",
        "created_at": "2024-02-20 14:30:00"
    }
}

وب‌هوک (Webhook)

توجه: سرور شما باید همیشه آماده دریافت درخواست از سمت ما باشد. ما نتیجه پرداخت را به صورت GET به URL شما ارسال می‌کنیم.

پارامترهای دریافتی

مثال: https://yoursite.com/verify.php?order_id=ORD-9821&status=confirmed&tx=...

پارامتر	توضیحات
`order_id`	همان شناسه سفارشی که هنگام ایجاد پرداخت ارسال کردید.
`status`	`confirmed`: پرداخت موفق `expired`: زمان پرداخت تمام شد `partial`: مبلغ واریزی کمتر از حد مجاز
`tx`	هش تراکنش (Transaction Hash) جهت پیگیری در اکسپلورر بلاکچین.

کدهای خطا

در صورت بروز خطا، فیلد 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'];
}