API Reference v2.0

مستندات درگاه پرداخت
کارت‌به‌کارت

راهنمای کامل یکپارچه‌سازی درگاه پرداخت — از ساخت تراکنش تا دریافت webhook با امضای HMAC

🌐 Base URL https://ariacart.ir
📦 Format JSON
🔐 Auth API Key
معرفی

درگاه پرداخت امکان پرداخت آنلاین با تأیید خودکار را فراهم می‌کند. یکپارچه‌سازی در سه مرحله انجام می‌شود.

تمام درخواست‌ها باید با Content-Type: application/json ارسال شوند. تمام مبالغ به ریال هستند.
API Key خود را هرگز در کد سمت کلاینت (JavaScript فرانت‌اند) قرار ندهید. تمام فراخوانی‌ها باید سمت سرور باشند.
فلوی پرداخت

مسیر کامل یک تراکنش از ابتدا تا پایان

سرور شما
POST /pay/create
لینک پرداخت
redirect کاربر
کاربر واریز
پرداخت توسط کاربر
تأیید خودکار
پردازش سیستم
Webhook
اطلاع‌رسانی
احراز هویت

برای ساخت تراکنش، API Key خود را در فیلد merchant در body درخواست ارسال کنید.

🔑
API Key از پنل مرچنت قابل مشاهده است. هر کسب‌وکار یک API Key مستقل دارد.
ساخت تراکنش

اولین قدم در فلوی پرداخت. یک تراکنش pending ایجاد و لینک پرداخت برمی‌گردد.

POST /pay/create ساخت تراکنش جدید
پارامترنوعوضعیتتوضیح
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]
  }'
201 Created — تراکنش ریالی ساخته شد
{
  "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"
}
201 Created — تراکنش کریپتو ساخته شد
{
  "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"
}
200 OK — تراکنش pending قبلی (idempotent)
{
  "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 وضعیت تراکنش از سمت صفحه پرداخت استفاده می‌شود. معمولاً نیازی به فراخوانی مستقیم از سرور ندارید.

GET /pay/status/:id/:token بررسی وضعیت
پارامترنوعتوضیح
id integer شناسه تراکنش
token string access_token دریافتی از /pay/create
200 OK
{
  "status":          "success",  // pending | success | failed | expired
  "remaining":       423,        // ثانیه تا انقضا
  "original_amount": 500000,
  "unique_amount":   500342,
  "tx_hash":         "abc123..."  // فقط برای تراکنش کریپتوی موفق
}
تأیید پرداخت

بعد از redirect کاربر به callback URL، می‌توانید وضعیت تراکنش را verify کنید.

POST /pay/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);
}
200 OK — پرداخت ریالی موفق
{
  "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"
}
200 OK — پرداخت کریپتو موفق
{
  "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"
}
Webhook Payload

پس از تأیید پرداخت، سرور یک درخواست POST به آدرس webhook شما ارسال می‌کند.

سرور شما باید با کد 200 پاسخ دهد. در صورت عدم پاسخ، تا ۳ بار (با فاصله زمانی) مجدداً تلاش می‌شود.
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

برای اطمینان از اینکه webhook واقعاً از سرور ما ارسال شده، هر درخواست دارای هدر X-Signature است.

🔐 نحوه verify کردن امضا
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 برگردانده می‌شود.
GET /pay/status/:id/:token polling وضعیت از سمت custom page

برای بررسی وضعیت تراکنش هر چند ثانیه یک‌بار این endpoint را poll کنید. id و token را از ریسپانس /pay/create می‌گیرید.

فلوی پیاده‌سازی custom payment page
// ۱. ساخت تراکنش
POST /pay/create → {
  transaction_id, access_token,
  card_number, owner_name, unique_amount, expires_at   // ریالی
  wallet_address, crypto_amount, network               // کریپتو
}

// ۲. نمایش اطلاعات پرداخت به کاربر (بدون ریدایرکت)
نمایش: شماره کارت / آدرس کیف‌پول، مبلغ یونیک، تایمر انقضا

// ۳. 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", ... }
نمونه کد JavaScript — polling
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); // هر ۵ ثانیه
}
Idempotency

برای جلوگیری از ساخت تراکنش تکراری در صورت شکست شبکه، هدر Idempotency-Key را ارسال کنید.

کلید Idempotency تا ۲۴ ساعت معتبر است. در صورت ارسال مجدد همان کلید، response اولیه برگردانده می‌شود.
💡 نحوه استفاده
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 آفلاین است
نمونه response خطا
{
  "ok":    false,
  "error": "اطلاعات merchant معتبر نیست"
}
WooCommerce Plugin

پلاگین رسمی WooCommerce — پشتیبانی از کارت‌ب‌کارت و کریپتو، با قابلیت نمایش اطلاعات پرداخت درون سایت (بدون ریدایرکت).

پلاگین WooCommerce نصب و تنظیم درگاه \u25be

پلاگین شامل دو درگاه جداگانه در 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
رفتار پلاگین
Redirect Mode
کاربر دکمه پرداخت زده → سفارش در WooCommerce → redirect ب‌صفحه درگاه → بازگشت به سایت → تأیید خودکار
Inline Mode
کاربر دکمه پرداخت زده → اطلاعات پرداخت در سایت نمایش داده می‌شود → polling خودکار → تأیید سفارش
Webhook سایت

پلاگین صفحه زیر را به صورت خودکار رزیستر می‌کند — نیازی به تنظیم دستی ندارید:

POST https://yoursite.com/wp-json/ariacart/v1/webhook