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 | عدد | مبلغ؛ بهصورت پیشفرض به تومان. الزامی. |
| amountUnit | toman | usdt | اگر usdt باشد، amount مقدار تتر است. اختیاری (پیشفرض toman). |
| currency | رشته | ارز پرداخت: USDT. الزامی. |
| description | رشته | توضیح سفارش (مثلاً شمارهٔ سفارش). الزامی. |
| webhookUrl | URL | آدرس دریافت وبهوک. اختیاری. |
| successUrl | URL | بازگشت مشتری پس از پرداخت موفق. اختیاری. |
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"
}'{
"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 https://tnetpay.com/api/payments/invoice/INV-...{
"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. در صورت خطا تا ۵ بار با فاصلهٔ فزاینده دوباره ارسال میشود.
{
"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
$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
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
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 | فاکتور پیدا نشد. |