API درگاه تتر (USDT BEP20)

با این API در هر سایت کدنویسی‌شده یک فاکتور پرداخت تتر می‌سازید، مشتری را به صفحهٔ پرداخت تی‌نت‌پی می‌فرستید و نتیجه را با وب‌هوک و بررسی وضعیت دریافت می‌کنید. پرداخت فقط با USDT روی شبکهٔ BEP20 (BNB Smart Chain) انجام می‌شود. برای ووکامرس از افزونهٔ درگاه تتر استفاده کنید.

احراز هویت و کلید API

کلید API را پس از ورود، از بخش «کلیدهای API» پنل بسازید. کلید فقط در پنل نمایش داده می‌شود؛ آن را سمت سرور نگه دارید و در هدر X-API-Key (یا Authorization: Bearer ...) بفرستید. حساب باید احراز هویت‌شده و فعال باشد.

آدرس پایه: https://tnetpay.com/api

ساخت فاکتور

POST /payments/gateway

فیلدنوعتوضیح
amountعددمبلغ؛ به‌صورت پیش‌فرض به تومان. الزامی.
amountUnittoman | usdtاگر usdt باشد، amount مقدار تتر است. اختیاری (پیش‌فرض toman).
currencyرشتهارز پرداخت: USDT. الزامی.
descriptionرشتهتوضیح سفارش (مثلاً شمارهٔ سفارش). الزامی.
webhookUrlURLآدرس دریافت وب‌هوک. اختیاری.
successUrlURLبازگشت مشتری پس از پرداخت موفق. اختیاری.
cURL
curl -X POST https://tnetpay.com/api/payments/gateway \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500000,
    "currency": "USDT",
    "description": "Order #1001",
    "webhookUrl": "https://shop.example/tnetpay/webhook",
    "successUrl": "https://shop.example/order/1001"
  }'
Response
{
  "success": true,
  "data": {
    "invoiceId": "INV-...",
    "paymentUrl": "https://tnetpay.com/pay/INV-...",
    "amount": 1500000,
    "currency": "USDT",
    "status": "pending",
    "successUrl": "https://shop.example/order/1001"
  }
}

invoiceId را روی سفارش ذخیره کنید و مشتری را به paymentUrl بفرستید. صفحهٔ پرداخت آدرس کیف پول، مقدار تتر و QR را نشان می‌دهد. هر فاکتور پس از ۳۰ دقیقه منقضی می‌شود.

بررسی وضعیت فاکتور

GET /payments/invoice/{invoiceId} — وضعیت‌ها: pending، paid، underpaid (کمتر از مبلغ واریز شده)، expired.

cURL
curl https://tnetpay.com/api/payments/invoice/INV-...
Response (fields abridged)
{
  "invoiceId": "INV-...",
  "amount": 1500000,
  "currency": "USDT",
  "cryptoAmount": "...",
  "status": "paid",
  "expiresAt": "...",
  "confirmations": 0,
  "successUrl": "..."
}

وب‌هوک

اگر webhookUrl داده باشید، با تغییر وضعیت یک POST با JSON ارسال می‌شود. رویدادها: payment.paid، payment.underpaid، payment.expired. هدرها: X-TNetPay-Event و X-TNetPay-Attempt. در صورت خطا تا ۵ بار با فاصلهٔ فزاینده دوباره ارسال می‌شود.

Webhook body
{
  "event": "payment.paid",
  "invoiceId": "INV-...",
  "amount": 1500000,
  "currency": "USDT",
  "cryptoAmount": "...",
  "status": "paid",
  "transactionHash": "0x...",
  "confirmations": 0,
  "timestamp": "..."
}

تأیید: قبل از تحویل سفارش، GET /payments/invoice/{invoiceId} را صدا بزنید و فقط اگر status برابر paid بود سفارش را پرداخت‌شده کنید. با کد 2xx پاسخ دهید و پردازش را تکرارپذیر بنویسید.

نمونه‌کد

PHP

PHP
<?php
$ch = curl_init('https://tnetpay.com/api/payments/gateway');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('TNETPAY_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 1500000, 'currency' => 'USDT', 'description' => 'Order #1001',
        'webhookUrl' => 'https://shop.example/tnetpay/webhook.php',
        'successUrl' => 'https://shop.example/order.php?id=1001',
    ]),
]);
$res = json_decode(curl_exec($ch), true);
if (!empty($res['success'])) { header('Location: ' . $res['data']['paymentUrl']); exit; }

Node.js

Node.js
const r = await fetch('https://tnetpay.com/api/payments/gateway', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.TNETPAY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 1500000, currency: 'USDT', description: 'Order #1001',
    webhookUrl: 'https://shop.example/tnetpay/webhook' }),
});
const { data } = await r.json();
// redirect the buyer to data.paymentUrl

// webhook: re-check before fulfilling
app.post('/tnetpay/webhook', express.json(), async (req, res) => {
  const inv = await (await fetch('https://tnetpay.com/api/payments/invoice/' + encodeURIComponent(req.body.invoiceId))).json();
  if (inv.status === 'paid') { /* mark order paid once */ }
  res.sendStatus(200);
});

Python

Python
import os, requests
r = requests.post("https://tnetpay.com/api/payments/gateway",
    headers={"X-API-Key": os.environ["TNETPAY_API_KEY"]},
    json={"amount": 1500000, "currency": "USDT", "description": "Order #1001",
          "webhookUrl": "https://shop.example/tnetpay/webhook"}, timeout=20)
payment_url = r.json()["data"]["paymentUrl"]

تسویه و حالت‌های دریافت

در تی‌نت‌پی دو حالت دریافت تتر وجود دارد: در حالت مستقیم، پرداخت به کیف پول خود شما واریز می‌شود؛ در حالت نگهداری، مبلغ به موجودی حساب شما در تی‌نت‌پی اضافه می‌شود و طبق تنظیمات تسویه قابل درخواست است. حالت و تنظیمات تسویه را در پنل، بخش «تنظیمات تسویه» مدیریت کنید.

خطاهای رایج

HTTPمعنی
401کلید API ارسال نشده یا نامعتبر است.
403حساب هنوز احراز هویت/تأیید نشده است.
400فیلدها نامعتبرند یا مبلغ از سقف مجاز حساب بیشتر است.
404فاکتور پیدا نشد.