درگاه پرداخت امکان پرداخت آنلاین با تأیید خودکار را فراهم میکند. یکپارچهسازی در سه مرحله انجام میشود.
Content-Type: application/json ارسال شوند. تمام مبالغ به ریال هستند.مسیر کامل یک تراکنش از ابتدا تا پایان
برای ساخت تراکنش، API Key خود را در فیلد merchant در body درخواست ارسال کنید.
اولین قدم در فلوی پرداخت. یک تراکنش pending ایجاد و لینک پرداخت برمیگردد.
| پارامتر | نوع | وضعیت | توضیح |
|---|---|---|---|
| merchant | string | required | API Key مرچنت |
| order_id | string | required | شناسه یکتای سفارش در سیستم شما (حداکثر ۲۵۵ کاراکتر - کارکترهای مجاز a-zA-Z0-9-_) |
| amount | integer | required | مبلغ به ریال — باید مثبت باشد |
| webhook | string | optional | آدرس دریافت نتیجه پرداخت (HTTPS توصیه میشود) |
| callback | string | optional | آدرس redirect کاربر پس از پرداخت موفق |
| payment_type | string | optional | نوع پرداخت: rial (پیشفرض) یا crypto |
| network | string | optional | شبکه کریپتو — فقط در صورت payment_type=crypto الزامی است: trc20 | erc20 | bep20 |
| card_ids | array[integer] | optional | لیست ID کارتهای مجاز برای این تراکنش — سیستم بر اساس توزیع بار بهترین کارت را انتخاب میکند. در صورت عدم ارسال، از تمام کارتهای فعال استفاده میشود. |
// PHP — ساخت تراکنش $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => 'https://ariacart.ir/pay/create', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'merchant' => 'YOUR_API_KEY', 'order_id' => 'ORDER_' . time(), 'amount' => 500000, 'webhook' => 'https://yoursite.com/webhook', 'callback' => 'https://yoursite.com/return', // اختیاری — محدود کردن به کارتهای مشخص 'card_ids' => [3, 7, 12], ]), ]); $response = json_decode(curl_exec($ch), true); curl_close($ch); if ($response['ok']) { $paymentUrl = $response['payment_url']; // redirect کاربر به $paymentUrl header('Location: ' . $paymentUrl); }
# Python — ساخت تراکنش import requests response = requests.post( 'https://ariacart.ir/pay/create', json={ 'merchant': 'YOUR_API_KEY', 'order_id': 'ORDER_12345', 'amount': 500000, 'webhook': 'https://yoursite.com/webhook', 'callback': 'https://yoursite.com/return', # اختیاری 'card_ids': [3, 7, 12], } ) data = response.json() if data['ok']: payment_url = f"{data['payment_url']}" # redirect کاربر به payment_url
// Go — ساخت تراکنش package main import ( "bytes" "encoding/json" "net/http" ) type CreateRequest struct { Merchant string `json:"merchant"` OrderID string `json:"order_id"` Amount int64 `json:"amount"` Webhook string `json:"webhook"` Callback string `json:"callback"` CardIDs []uint `json:"card_ids,omitempty"` } func createTransaction() { body, _ := json.Marshal(CreateRequest{ Merchant: "YOUR_API_KEY", OrderID: "ORDER_12345", Amount: 500000, Webhook: "https://yoursite.com/webhook", Callback: "https://yoursite.com/return", CardIDs: []uint{3, 7, 12}, // اختیاری }) resp, _ := http.Post( "https://ariacart.ir/pay/create", "application/json", bytes.NewBuffer(body), ) defer resp.Body.Close() var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) // result["payment_url"] → لینک پرداخت }
// Node.js — ساخت تراکنش const response = await fetch('https://ariacart.ir/pay/create', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant: 'YOUR_API_KEY', order_id: `ORDER_${Date.now()}`, amount: 500000, webhook: 'https://yoursite.com/webhook', callback: 'https://yoursite.com/return', card_ids: [3, 7, 12], // اختیاری }), }); const data = await response.json(); if (data.ok) { const paymentUrl = `${data.payment_url}`; // res.redirect(paymentUrl) }
# cURL curl -X POST https://ariacart.ir/pay/create \ -H "Content-Type: application/json" \ -d '{ "merchant": "YOUR_API_KEY", "order_id": "ORDER_12345", "amount": 500000, "webhook": "https://yoursite.com/webhook", "callback": "https://yoursite.com/return", "card_ids": [3, 7, 12] }'
{
"ok": true,
"transaction_id": 1842,
"access_token": "a3f8c2d1...",
"payment_url": "https://ariacart.ir/pay/t/1842/a3f8c2d1...",
"unique_amount": 500342,
"card_number": "6037991234567890",
"owner_name": "علی محمدی",
"expires_at": "2026-04-27T15:30:00Z"
}
{
"ok": true,
"transaction_id": 1843,
"access_token": "b7e1a4f2...",
"payment_url": "https://ariacart.ir/pay/t/1843/b7e1a4f2...",
"unique_amount": 500000,
"expires_at": "2026-04-27T15:30:00Z",
"payment_type": "crypto",
"network": "trc20",
"wallet_address": "TRx9K...mN4q",
"crypto_amount": "13.52"
}
{
"ok": true,
"transaction_id": 1842,
"access_token": "a3f8c2d1...",
"payment_url": "https://ariacart.ir/pay/t/1842/a3f8c2d1...",
"unique_amount": 500342,
"card_number": "6037991234567890",
"owner_name": "علی محمدی",
"expires_at": "2026-04-27T15:30:00Z"
}
برای polling وضعیت تراکنش از سمت صفحه پرداخت استفاده میشود. معمولاً نیازی به فراخوانی مستقیم از سرور ندارید.
| پارامتر | نوع | توضیح |
|---|---|---|
| id | integer | شناسه تراکنش |
| token | string | access_token دریافتی از /pay/create |
{
"status": "success", // pending | success | failed | expired
"remaining": 423, // ثانیه تا انقضا
"original_amount": 500000,
"unique_amount": 500342,
"tx_hash": "abc123..." // فقط برای تراکنش کریپتوی موفق
}
بعد از redirect کاربر به callback URL، میتوانید وضعیت تراکنش را verify کنید.
| پارامتر | نوع | وضعیت | توضیح |
|---|---|---|---|
| merchant | string | required | API Key مرچنت |
| order_id | string | required | شناسه سفارش |
| access_token | string | required | توکن دریافتی از /pay/create |
// PHP — verify پرداخت در callback URL $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => 'https://ariacart.ir/pay/verify', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'merchant' => 'YOUR_API_KEY', 'order_id' => $_GET['order_id'], 'access_token' => $_GET['token'], ]), ]); $res = json_decode(curl_exec($ch), true); curl_close($ch); if ($res['ok'] && $res['status'] === 'success') { // پرداخت موفق — سفارش را نهایی کنید fulfillOrder($res['order_id'], $res['amount']); }
# Python — verify پرداخت import requests res = requests.post('https://ariacart.ir/pay/verify', json={ 'merchant': 'YOUR_API_KEY', 'order_id': order_id, 'access_token': access_token, }).json() if res['ok'] and res['status'] == 'success': fulfill_order(res['order_id'], res['amount'])
// Go — verify پرداخت type VerifyRequest struct { Merchant string `json:"merchant"` OrderID string `json:"order_id"` AccessToken string `json:"access_token"` } body, _ := json.Marshal(VerifyRequest{ Merchant: "YOUR_API_KEY", OrderID: orderID, AccessToken: token, }) resp, _ := http.Post( "https://ariacart.ir/pay/verify", "application/json", bytes.NewBuffer(body), ) var result map[string]interface{} json.NewDecoder(resp.Body).Decode(&result) // result["status"] == "success" → پرداخت موفق
// Node.js — verify پرداخت const res = await fetch('https://ariacart.ir/pay/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant: 'YOUR_API_KEY', order_id: orderId, access_token: token, }), }).then(r => r.json()); if (res.ok && res.status === 'success') { await fulfillOrder(res.order_id, res.amount); }
{
"ok": true,
"status": "success",
"transaction_id": 1842,
"order_id": "ORDER_12345",
"amount": 500000,
"unique_amount": 500342,
"payer_card": "****1234",
"verified_at": "2026-04-27T14:30:00Z"
}
{
"ok": true,
"status": "success",
"transaction_id": 1843,
"order_id": "ORDER_12346",
"amount": 500000,
"unique_amount": 500000,
"verified_at": "2026-04-27T14:31:00Z",
"payment_type": "crypto",
"network": "trc20",
"tx_hash": "f4a2b1c9d8e7...",
"crypto_amount": "13.52"
}
پس از تأیید پرداخت، سرور یک درخواست POST به آدرس webhook شما ارسال میکند.
// پرداخت ریالی { "event": "payment.success", "transaction_id": 1842, "order_id": "ORDER_12345", "amount": 500000, "unique_amount": 500342, "commission_amount":15000, "payer_card": "****1234", "paid_at": "2026-04-27T14:30:00Z" } // پرداخت کریپتو { "event": "payment.success", "transaction_id": 1843, "order_id": "ORDER_12346", "amount": 500000, "unique_amount": 500000, "commission_amount":15000, "payment_type": "crypto", "network": "trc20", "tx_hash": "f4a2b1c9d8e7...", "crypto_amount": "13.52", "paid_at": "2026-04-27T14:31:00Z" }
برای اطمینان از اینکه webhook واقعاً از سرور ما ارسال شده، هر درخواست دارای هدر X-Signature است.
signature = "sha256=" + HMAC-SHA256(webhook_secret, request_body)
X-Signature: sha256=a1b2c3d4e5f6...
// PHP — verify امضای webhook $secret = 'YOUR_WEBHOOK_SECRET'; $payload = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_SIGNATURE'] ?? ''; $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret); if (!hash_equals($expected, $signature)) { http_response_code(401); exit('Unauthorized'); } $data = json_decode($payload, true); if ($data['event'] === 'payment.success') { fulfillOrder($data['order_id'], $data['amount']); http_response_code(200); echo 'OK'; }
# Python (Flask) — verify امضای webhook import hmac, hashlib from flask import Flask, request app = Flask(__name__) SECRET = b'YOUR_WEBHOOK_SECRET' @app.route('/webhook', methods=['POST']) def webhook(): payload = request.get_data() signature = request.headers.get('X-Signature', '') expected = 'sha256=' + hmac.new( SECRET, payload, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature): return 'Unauthorized', 401 data = request.get_json() if data['event'] == 'payment.success': fulfill_order(data['order_id'], data['amount']) return 'OK', 200
// Go — verify امضای webhook import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" "io" "net/http" ) func webhookHandler(w http.ResponseWriter, r *http.Request) { secret := []byte("YOUR_WEBHOOK_SECRET") body, _ := io.ReadAll(r.Body) sig := r.Header.Get("X-Signature") mac := hmac.New(sha256.New, secret) mac.Write(body) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(expected), []byte(sig)) { http.Error(w, "Unauthorized", 401) return } // پردازش payload ... fmt.Fprintln(w, "OK") }
// Node.js (Express) — verify امضای webhook const crypto = require('crypto'); app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => { const secret = 'YOUR_WEBHOOK_SECRET'; const signature = req.headers['x-signature'] || ''; const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(req.body) .digest('hex'); if (!crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signature) )) { return res.status(401).send('Unauthorized'); } const data = JSON.parse(req.body); if (data.event === 'payment.success') { await fulfillOrder(data.order_id, data.amount); } res.send('OK'); });
اگر میخواهید صفحه پرداخت را خودتان طراحی کنید و نیازی به ریدایرکت کاربر به درگاه نداشته باشید، میتوانید از فیلدهای اضافه ریسپانس /pay/create استفاده کنید.
/pay/create برگردانده میشود.روش تأیید تراکنش به تنظیمات مرچنت بستگی دارد:
- تأیید از طریق بلاکچین (حالت پیشفرض): سیستم بهصورت خودکار شبکه را poll میکند. اگر صفحه پرداخت را خودتان پیادهسازی کردهاید، کاربر حتماً باید پس از واریز، درخواست بررسی را از طریق
POST /pay/crypto/checkارسال کند تا اسکن شبکه اجرا شود. - تأیید از طریق App Listener (SMS/نوتیفیکیشن): تأیید بهصورت خودکار از طریق اپلیکیشن انجام میشود و نیازی به فراخوانی
/pay/crypto/checkنیست — polling روی/pay/statusکافی است.
برای بررسی وضعیت تراکنش هر چند ثانیه یکبار این endpoint را poll کنید. id و token را از ریسپانس /pay/create میگیرید.
// ۱. ساخت تراکنش کریپتو POST /pay/create → { transaction_id, access_token, wallet_address, crypto_amount, network, expires_at } // ۲. نمایش آدرس + مبلغ به کاربر // ۳. کاربر واریز میکند → ارسال درخواست بررسی (الزامی) POST /pay/crypto/check → { ok: true } // ۴. polling نتیجه GET /pay/status/{transaction_id}/{access_token} → { status: "pending" | "success" | "expired" | "failed" } // ۵. بعد از status=success → verify از سرور POST /pay/verify → { ok: true, ... }
// ۱. ساخت تراکنش کریپتو POST /pay/create → { transaction_id, access_token, ... } // ۲. نمایش اطلاعات به کاربر // ۳. polling وضعیت — تأیید خودکار از سمت سرور انجام میشود GET /pay/status/{transaction_id}/{access_token} → { status: "pending" | "success" | "expired" | "failed", remaining: 423 } // ۴. بعد از status=success → verify از سرور POST /pay/verify → { ok: true, status: "success", ... }
async function pollPaymentStatus(txId, token, onSuccess, onExpire) { const interval = setInterval(async () => { const res = await fetch(`/pay/status/${txId}/${token}`).then(r => r.json()); if (res.status === "success") { clearInterval(interval); onSuccess(); } else if (res.status === "expired" || res.remaining <= 0) { clearInterval(interval); onExpire(); } }, 5000); // هر ۵ ثانیه }
اگر پرداخت کریپتو را بدون ریدایرکت پیادهسازی کردهاید و میخواهید کاربر با کلیک دکمه، شبکه را بررسی کند، از این endpoint استفاده کنید. بین هر درخواست حداقل ۳۰ ثانیه باید فاصله باشد.
/pay/status قابل دریافت است.فقط در حالت تأیید از بلاکچین نیاز است. اگر مرچنت از App Listener استفاده میکند، تأیید خودکار انجام میشود و نیازی به فراخوانی این endpoint نیست.
| فیلد | نوع | توضیح |
|---|---|---|
merchant | string | API Key مرچنت — الزامی |
transaction_id | number | شناسه تراکنش از ریسپانس /pay/create — الزامی |
access_token | string | توکن دسترسی از ریسپانس /pay/create — الزامی |
HTTP 200
{
"ok": true,
"message": "درحال بررسی شبکه..."
}
HTTP 429
{
"ok": false,
"error": "درخواست زود است",
"retry_after": 28 // ثانیه تا درخواست بعدی
}
// ۱. ساخت تراکنش کریپتو POST /pay/create → { transaction_id, access_token, wallet_address, crypto_amount, network, expires_at } // ۲. نمایش آدرس + مبلغ به کاربر (بدون ریدایرکت) // ۳. کاربر واریز میکند و روی دکمه بررسی کلیک میکند POST /pay/crypto/check → { ok: true } → در پسزمینه شبکه اسکن میشود // ۴. نتیجه از طریق polling یا webhook GET /pay/status/{transaction_id}/{access_token} → { status: "success" | "pending" | "expired" }
// JavaScript — بررسی دستی + polling نتیجه async function checkCryptoTx(merchantKey, txId, token) { const res = await fetch('/pay/crypto/check', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant: merchantKey, transaction_id: txId, access_token: token }) }).then(r => r.json()); if (!res.ok) { if (res.retry_after) { console.log(`rate limited — retry in ${res.retry_after}s`); } return; } // ۳ ثانیه صبر، سپس وضعیت را چک کن await new Promise(r => setTimeout(r, 3000)); const status = await fetch(`/pay/status/${txId}/${token}`) .then(r => r.json()); if (status.status === 'success') { // تراکنش تایید شد — verify از سرور خودتان verifyFromServer(txId, token); } }
// PHP — بررسی دستی تراکنش کریپتو $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => 'https://c2c.lm8.ir/pay/crypto/check', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'merchant' => $merchant_key, 'transaction_id' => $tx_id, 'access_token' => $access_token, ]), ]); $res = json_decode(curl_exec($ch), true); if ($res['ok']) { // ۳ ثانیه صبر، سپس وضعیت را بررسی کن sleep(3); // GET /pay/status/{tx_id}/{access_token} }
# Python — بررسی دستی تراکنش کریپتو import requests, time res = requests.post('https://c2c.lm8.ir/pay/crypto/check', json={ 'merchant': merchant_key, 'transaction_id': tx_id, 'access_token': access_token, }).json() if res['ok']: time.sleep(3) status = requests.get( f'https://c2c.lm8.ir/pay/status/{tx_id}/{access_token}' ).json() if status['status'] == 'success': # verify از سرور خودتان verify_payment(tx_id, access_token) elif res.get('retry_after'): print(f"rate limited, retry in {res['retry_after']}s")
برای جلوگیری از ساخت تراکنش تکراری در صورت شکست شبکه، هدر Idempotency-Key را ارسال کنید.
POST /pay/create
Idempotency-Key: unique-key-per-request-12345
Content-Type: application/json
در صورت خطا، فیلد error در response حاوی توضیح فارسی خواهد بود.
| HTTP Code | error | توضیح |
|---|---|---|
| 400 | پارامترهای ورودی ناقص است | یکی از فیلدهای required ارسال نشده |
| 401 | اطلاعات merchant معتبر نیست | API Key اشتباه یا غیرفعال |
| 403 | دسترسی از این IP مجاز نیست | IP شما در whitelist مرچنت نیست |
| 409 | این سفارش قبلاً پرداخت شده | order_id تکراری با وضعیت success |
| 410 | تراکنش قبلی منقضی شده | order_id تکراری با وضعیت expired |
| 402 | درگاه موقتاً غیرفعال است | موجودی کیف پول کافی نیست |
| 503 | درگاه در دسترس نیست | listener آفلاین است |
{
"ok": false,
"error": "اطلاعات merchant معتبر نیست"
}
پلاگین رسمی WooCommerce — پشتیبانی از کارتبکارت و کریپتو، با قابلیت نمایش اطلاعات پرداخت درون سایت (بدون ریدایرکت).
پلاگین شامل دو درگاه جداگانه در WooCommerce است:
| درگاه | شناسه | توضیح |
|---|---|---|
| کارت بکارت | ariacart_c2c | پرداخت ریالی کارتبکارت |
| کریپتو | ariacart_crypto | پرداخت با USDT روی TRC20 ، ERC20 ، BEP20 |
1. فایل zip پلاگین را دانلود کنید 2. از پنل وردپرس ← سرایپنه ← افزونهها ، گزینه زپ بارگذاری را بزنید 3. پلاگین AriaCart را اپلود و فعال کنید 4. از WooCommerce ← Settings ← Payments ، درگاه مورد نظر را فعال کنید 5. API Key را وارد کنید و نحوه نمایش را انتخاب کنید
| پارامتر | توضیح |
|---|---|
| API Key | کلید API درگاه AriaCart |
| Webhook Secret | برای تأیید امضای HMAC روی webhook (اختیاری) |
| نحوه نمایش | ریدایرکت بصفحه درگاه | نمایش اطلاعات درون سایت (بدون ریدایرکت) |
| شبکه (crypto) | انتخاب خودکار | TRC20 | ERC20 | BEP20 |
پلاگین صفحه زیر را به صورت خودکار رزیستر میکند — نیازی به تنظیم دستی ندارید:
POST https://yoursite.com/wp-json/ariacart/v1/webhook