API پرداخت نسخه ۲

شروع سریع

۱. در داشبورد، بخش توسعه‌دهندگان، برای درگاه خود یک کلید API بسازید. ۲. با مبلغ سفارش یک پرداخت بسازید. ۳. مشتری را به checkout_url برگشتی هدایت کنید. ۴. وقتی وب‌هوک رسید (یا مشتری برگشت)، پرداخت را دوباره بخوانید و وقتی وضعیت آن "paid" بود سفارش را ارسال کنید.

 curl https://coino.live/api/v2/payments \
  -H "Authorization: Bearer ck_live_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "currency": "EUR", "order_id": "1001",
       "success_url": "https://shop.example/thanks",
       "notify_url": "https://shop.example/coino-webhook"}' 

احراز هویت

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

Authorization: Bearer ck_live_...
نشانی پایه: https://coino.live/api/v2

همه مبالغ رشته اعشاری هستند (نه عدد)، همه زمان‌ها ISO 8601 به وقت UTC هستند و هر پاسخ JSON است و نتیجه زیر "data" قرار دارد.

ایجاد پرداخت

قیمت می‌تواند به دلار یا هر ارزی باشد که GET /currencies برمی‌گرداند؛ ارزهای دیگر هنگام ساخت پرداخت با نرخ روز به دلار تبدیل می‌شوند. مشتری کوین و شبکه را در صفحه پرداخت انتخاب می‌کند.

پاسخ (۲۰۱ هنگام ساخت، ۲۰۰ برای کلید تکراری) شیء پرداخت زیر است.

شیء پرداخت

{
  "data": {
    "id": "01m62ewd502p9774d6trd7rhr7",
    "status": "paid",
    "amount": "22.32",
    "currency": "USD",
    "requested_amount": "20.00",
    "requested_currency": "EUR",
    "exchange_rate_usd": "1.115926958947",
    "received_usd": "22.32",
    "remaining_usd": "0.00",
    "order_id": "943",
    "description": "Order #943",
    "customer_email": "[email protected]",
    "metadata": {"cart": "abc"},
    "checkout_url": "https://coino.live/pay/01m62ewd502p9774d6trd7rhr7",
    "success_url": "https://shop.example/thanks",
    "cancel_url": "https://shop.example/cart",
    "asset": null,
    "quote": {
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "address": "0x8e2e…61bc", "amount": "22.330545",
      "network_fee": "0.000001", "rate_usd": "0.9995", "expires_at": "…"
    },
    "deposits": [{
      "asset": "usdc-ethereum", "symbol": "USDC", "network": "Ethereum",
      "tx_hash": "0xf13d…1439", "explorer_url": "https://etherscan.io/tx/0xf13d…1439",
      "amount": "22.330545", "network_fee": "0.000001",
      "platform_fee": "0.223305", "net": "22.107239",
      "usd_value": "22.32", "credited_at": "…"
    }],
    "expires_at": "…", "paid_at": "…", "created_at": "…"
  }
}

amount و currency مبلغی است که مشتری به دلار می‌پردازد؛ requested_amount و requested_currency همان چیزی است که شما درخواست کردید. quote کوین، نشانی و مبلغی است که اکنون به مشتری نمایش داده می‌شود؛ deposits همه تراکنش‌های دریافتی را همراه با کارمزد کسرشده و مبلغ افزوده‌شده به موجودی شما (net) فهرست می‌کند.

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

خواندن و لغو پرداخت‌ها

هر وقت به وضعیت فعلی پرداخت نیاز دارید آن را دوباره بخوانید: پس از وب‌هوک، هنگام بازگشت مشتری یا در یک کار زمان‌بندی‌شده. شناسه‌های ناشناخته و پرداخت‌های درگاه‌های دیگر پاسخ ۴۰۴ می‌دهند.

پرداخت‌های شما را از جدیدترین، ۵۰ مورد در هر صفحه فهرست می‌کند. هر دو فیلتر اختیاری‌اند. meta.next_cursor و meta.prev_cursor برای ورق زدن نتایج است.

پرداخت بازی را که هیچ مبلغی دریافت نکرده لغو می‌کند، مثلاً وقتی مشتری سبد خرید را خالی می‌کند. پرداخت‌هایی که واریزی دارند قابل لغو نیستند (۴۲۲).

وب‌هوک‌ها

هر بار وضعیت پرداخت تغییر کند، Coino Live یک درخواست POST به notify_url (یا نشانی وب‌هوک درگاه) می‌فرستد. وب‌هوک فقط وقتی ارسال می‌شود که درگاه شما کلید امضا داشته باشد: آن را در تنظیمات درگاه بسازید.

 POST /coino-webhook
X-Coino-Event: payment.paid
X-Coino-Delivery: 01m62f23xhkz39ahqv4h64ttfk
X-Coino-Signature: t=1761696953,v1=5f2c…

{"id": "01m62f23xhkz39ahqv4h64ttfk", "event": "payment.paid",
 "created_at": "…", "data": { …the payment object… }} 

امضا را بررسی کنید: HMAC-SHA256 رشته "<t>.<raw body>" را با کلید امضای خود حساب کنید، آن را در زمان ثابت با v1 مقایسه کنید و زمان‌های قدیمی‌تر از پنج دقیقه را رد کنید.

// PHP
$header = $_SERVER['HTTP_X_COINO_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $sig);
$ok = isset($sig['t'], $sig['v1'])
    && abs(time() - (int) $sig['t']) <= 300
    && hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = Math.abs(Date.now() / 1000 - t) <= 300
  && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

# Python
t, v1 = (p.split('=', 1)[1] for p in header.split(','))
expected = hmac.new(secret.encode(), f'{t}.{raw_body}'.encode(), 'sha256').hexdigest()
ok = abs(time.time() - int(t)) <= 300 and hmac.compare_digest(expected, v1)

ارزها، کوین‌ها و موجودی

ارزهایی که پرداخت می‌تواند با آن‌ها قیمت‌گذاری شود، هر کدام با ارزش دلاری: {"code": "EUR", "usd_per_unit": "1.09"}. اگر ارز فروشگاه شما در فهرست نیست، پرداخت رمزارزی را نمایش ندهید.

کوین‌هایی که مشتری اکنون می‌تواند با آن‌ها بپردازد: code (مثلاً "usdt-tron")، symbol، name، network، decimals و price_usd.

موجودی حساب شما برای هر کوین، پس از کسر کارمزد: asset، symbol، network، balance و usd_value (تا وقتی قیمتی در دسترس نیست null است).

حساب‌های کاستودی

برای اپلیکیشن‌هایی که حساب کاربری دارند: هر کاربر نشانی‌های واریز دائمی می‌گیرد و واریزها به موجودی همان کاربر در درگاه شما اعتبار می‌شود.

برداشت‌ها

از موجودی شما به یک آدرس پرداخت می‌کند: asset، amount و address الزامی‌اند؛ custody_user هزینه را از موجودی یک کاربر کاستودی برمی‌دارد؛ reference (یکتا در هر درگاه) تکرار درخواست را بی‌خطر می‌کند. به‌طور پیش‌فرض خاموش است: برداشت API را در تنظیمات درگاه روشن کنید؛ همان‌جا سقف روزانه دلاری و آدرس‌های IP سرورهای مجاز را تعیین می‌کنید (هر دو endpoint فقط به همین IPها پاسخ می‌دهند). reference تکراری برای برداشتی متفاوت با کد 409 رد می‌شود. برداشت‌های بزرگ ممکن است منتظر بررسی بمانند.

وضعیت: pending_review، approved، processing، broadcast، completed، rejected (به error نگاه کنید)، cancelled یا failed. پس از ارسال، tx_hash پر می‌شود.

خطاها و محدودیت‌ها

{"message": "The minimum payment is 1.00 USD."}

{"message": "amount must be a decimal string with at most 2 decimals, e.g. \"25.00\".",
 "errors": {"amount": ["amount must be a decimal string with at most 2 decimals, e.g. \"25.00\"."]}}

کتابخانه‌های برنامه‌نویسی

کتابخانه‌های رسمی این API، بدون هیچ وابستگی. امضای وب‌هوک‌ها را بررسی می‌کنند، برای هر درخواست ردشده خطای روشنی می‌دهند و خطاهای شبکه را فقط وقتی تکرار درخواست بی‌خطر است دوباره امتحان می‌کنند.

// PHP
$coino = new \CoinoLive\Client('ck_live_...');
$payment = $coino->payments->create(['amount' => '25.00', 'currency' => 'EUR', 'order_id' => '1001']);

// Node.js
const coino = new CoinoLive('ck_live_...');
const payment = await coino.payments.create({ amount: '25.00', currency: 'EUR', order_id: '1001' });

# Python
coino = coinolive.Client("ck_live_...")
payment = coino.payments.create(amount="25.00", currency="EUR", order_id="1001") 

هر فایل دانلود یک README دارد با همه فراخوانی‌ها، نحوه رسیدگی به وب‌هوک‌ها و کلاس‌های خطا.

یکپارچه‌سازی با پلتفرم‌ها

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

پلتفرم‌های دیگر: مستقیماً از API همان‌طور که در بالا آمده استفاده کنید.