مستندات API

پیش از شروع

هر درخواست کلید API را در سرآیند Authorization: Bearer … می‌خواهد. کلید را از داشبورد، بخش «API و ووکامرس» بسازید. دو نوع کلید هست:

• sk_test_… آزمایشی: رایگان، حتی پیش از خرید اشتراک. سفارش آزمایشی می‌سازد که پول واقعی نمی‌خواهد و با «شبیه‌سازی واریز» پرداخت می‌شود.
• sk_live_… اصلی: با اشتراک فعال. سفارش واقعی که با پیامک بانک تأیید می‌شود.

کلید را فقط روی سرور نگه دارید؛ هرگز در کد سمت مرورگر یا اپ موبایل نگذارید. سقف درخواست: ۱۲۰ در دقیقه برای هر کلید.

ساخت سفارش

POST /orders یک سفارش با مبلغ یکتا می‌سازد و لینک پرداخت برمی‌گرداند. سه رقم آخر مبلغ برای هر سفارش عوض می‌شود تا واریز مشتری فقط با همین سفارش جور دربیاید.

# create an order (amounts in Toman)
curl -X POST https://tayidshod.ir/api/v1/orders \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1888000, "order_id": "1042",
       "callback_url": "https://shop.example/hooks/tayidshod",
       "return_url": "https://shop.example/thanks"}' 

پاسخ 201:

{
  "id": "ord_7Gk2xQmN4pLs9T",
  "order_id": "1042",
  "mode": "test",
  "status": "pending",
  "amount": 1888000,
  "pay_amount": 1888437,
  "pay_amount_rial": 18884370,
  "currency": "IRT",
  "pay_url": "https://tayidshod.ir/p/ord_7Gk2xQmN4pLs9T",
  "card": { "number": "6219861000001239", "holder": "کافه مهتاب", "bank": "سامان", "sheba": null },
  "description": null,
  "customer": null,
  "callback_url": "https://shop.example/hooks/tayidshod",
  "return_url": "https://shop.example/thanks",
  "created_at": "2026-10-15T19:11:00Z",
  "expires_at": "2026-10-15T19:41:00Z",
  "paid_at": null,
  "deposit": null
}

مشتری را به pay_url بفرستید؛ یا pay_amount و شماره‌ی کارت را در صفحه‌ی خودتان نشان دهید.

تکرار امن: اگر همان order_id را با همان مبلغ دوباره بفرستید و سفارش هنوز باز باشد، همان سفارش با کد 200 برمی‌گردد. با مبلغ دیگر، خطای 409 می‌گیرید.

دیدن سفارش

GET /orders/{id} با شناسه‌ی ord_… یا order_id خودتان. یا GET /orders?order_id=1042. فهرست: GET /orders?status=paid&limit=20.

POST /orders/{id}/cancel سفارش باز را لغو می‌کند.

حالت آزمایشی

با کلید sk_test هر چیزی را بدون پول واقعی امتحان کنید. سفارش آزمایشی را این‌طور پرداخت کنید (یا دکمه‌ی «شبیه‌سازی واریز» را در صفحه‌ی پرداخت بزنید):

curl -X POST https://tayidshod.ir/api/v1/orders/ord_7Gk2xQmN4pLs9T/simulate-payment \
  -H "Authorization: Bearer sk_test_…"

وب‌هوک order.paid درست مثل حالت اصلی، با "mode": "test" فرستاده می‌شود.

وب‌هوک

با هر تغییر وضعیت یک درخواست POST می‌فرستیم:

POST https://shop.example/hooks/tayidshod
Content-Type: application/json
X-Tayidshod-Event: order.paid
X-Tayidshod-Delivery: evt_Qm3x…
X-Tayidshod-Signature: sha256=5f1c…

{ "id": "evt_Qm3x…", "event": "order.paid", "created_at": "2026-10-15T19:12:06Z", "mode": "live",
  "order": { "id": "ord_7Gk2xQmN4pLs9T", "order_id": "1042", "status": "paid", "pay_amount": 1888437, … } }

امضا را حتماً چک کنید: HMAC-SHA256 روی بدنه‌ی خام درخواست با «رمز امضا»ی داشبورد (whsec_…).

// PHP
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_TAYIDSHOD_SIGNATURE'] ?? '';
$ok  = hash_equals('sha256=' . hash_hmac('sha256', $raw, 'whsec_…'), $sig);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);

// Node.js (Express: use express.raw() for this route)
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', 'whsec_…').update(req.body).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Tayidshod-Signature') || ''));

با هر پاسخ 2xx تحویل تمام است. در غیر این صورت ۱، ۵ و ۱۵ دقیقه، ۱، ۳، ۶ و ۱۲ ساعت بعد دوباره می‌فرستیم. رویداد ممکن است بیش از یک بار برسد؛ با id رویداد یا وضعیت سفارش، تکراری‌ها را نادیده بگیرید.

برگشت مشتری

بعد از پرداخت، مشتری با دکمه‌ی «برگشت به فروشگاه» به return_url می‌رود و این پارامترها به آن اضافه می‌شود: tayidshod_id، order_id و status.

حساب

GET /account وضعیت اشتراک، باز یا متوقف بودن سفارش واقعی (live_orders.open و reason)، کارمزد پرداخت‌نشده، کارت‌ها و نشانی وب‌هوک را برمی‌گرداند. برای «تست اتصال» در افزونه‌ها مناسب است.

ارسال پیامک بانک

اپ اندروید «تأیید شد» این کار را خودش انجام می‌دهد. اگر ابزار خودتان را می‌سازید، پیامک‌های واریز گوشی را با «کد اتصال گوشی» (از داشبورد، بخش گوشی پیامک) بفرستید:

curl -X POST https://tayidshod.ir/api/v1/sms \
  -H "Authorization: Device dv_…" \
  -H "Content-Type: application/json" \
  -d '{"sender": "BankSaman", "body": "…متن کامل پیامک…", "received_at": "2026-10-15T19:12:01Z"}'
# → {"result": "matched", "order": "ord_7Gk2xQmN4pLs9T"}

نتیجه یکی از این‌هاست: matched، mismatch، unmatched، duplicate، ignored (برداشت یا پیامک دیگر)، unreadable. موجودی حساب پیش از ذخیره پوشانده می‌شود.

افزونه‌ی ووکامرس

1. افزونه را از داشبورد، بخش «API و ووکامرس» دانلود کنید و در وردپرس از «افزونه‌ها ← افزودن ← بارگذاری افزونه» نصب کنید.
2. ووکامرس ← تنظیمات ← پرداخت‌ها ← «تأیید شد»: کلید API و رمز وب‌هوک را وارد و فعال کنید. پیام سبز «متصل به …» یعنی همه‌چیز درست است.
3. با کلید آزمایشی یک خرید امتحانی بزنید؛ در صفحه‌ی پرداخت «شبیه‌سازی واریز» را بزنید. سفارش ووکامرس «در حال انجام» می‌شود.
4. کلید را با sk_live عوض کنید.

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

خطاها

پاسخ خطا: {"error": {"code": "…", "message": "…"}}. پیام‌ها فارسی و قابل نمایش به کاربرند.