مستندات API

آدرس پایه API به‌صورت زیر است. تمام مسیرها نسبت به این آدرس تعریف می‌شوند:

https://api.zargate.ir

مبالغ همواره بر حسب ریال و به‌صورت عدد صحیح ارسال می‌شوند. شناسه‌ها رشته‌ای هستند و هر تراکنش با یک trackingCode یکتا شناخته می‌شود.

احراز هویت از طریق کلید API انجام می‌شود. کلید را در پنل بازرگان بسازید و در هدر Authorization به‌صورت Bearer ارسال کنید. کلید را هرگز در سمت کلاینت یا کد عمومی قرار ندهید.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

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

پارامترهای بدنه درخواست

• amount (number، الزامی) — مبلغ به ریال.
• currency (string، الزامی) — واحد پول، مثلاً IRR.
• orderId (string، الزامی) — شناسه سفارش در سیستم شما.
• callbackUrl (string، الزامی) — آدرس بازگشت کاربر پس از پرداخت.
• description (string، اختیاری) — توضیح تراکنش.

نمونه درخواست

POST /api/v1/payments HTTP/1.1
Host: api.zargate.ir
Authorization: Bearer sk_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 500000,
  "currency": "IRR",
  "orderId": "ORDER-1024",
  "callbackUrl": "https://shop.example.com/callback",
  "description": "خرید سفارش ۱۰۲۴"
}

نمونه پاسخ

HTTP/1.1 201 Created
Content-Type: application/json

{
  "trackingCode": "ZG-7F3A9C2E",
  "status": "pending",
  "amount": 500000,
  "currency": "IRR",
  "orderId": "ORDER-1024",
  "paymentUrl": "https://portal.zargate.ir/pay/ZG-7F3A9C2E",
  "expiresAt": "2026-05-29T12:30:00Z"
}

پس از دریافت پاسخ، کاربر را به آدرس صفحه پرداخت میزبانی‌شده هدایت کنید. الگوی این آدرس به‌صورت زیر است و با trackingCode ساخته می‌شود:

https://portal.zargate.ir/pay/{trackingCode}

// مثال
window.location.href =
  "https://portal.zargate.ir/pay/ZG-7F3A9C2E";

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

پس از بازگشت کاربر به callbackUrl، وضعیت نهایی پرداخت را با کد رهگیری استعلام کنید. تا زمانی که نتیجه را از این نقطه پایانی (یا وب‌هوک) تأیید نکرده‌اید، تراکنش را موفق فرض نکنید.

GET /api/v1/payments/verify?trackingCode=ZG-7F3A9C2E HTTP/1.1
Host: api.zargate.ir
Authorization: Bearer sk_live_xxxxxxxxxxxx

نمونه پاسخ

HTTP/1.1 200 OK
Content-Type: application/json

{
  "trackingCode": "ZG-7F3A9C2E",
  "status": "completed",
  "amount": 500000,
  "orderId": "ORDER-1024",
  "referenceId": "100200300",
  "cardPan": "6219-86**-****-1234",
  "paidAt": "2026-05-29T12:05:11Z"
}

می‌توانید یک آدرس وب‌هوک در پنل ثبت کنید تا رویدادها به‌صورت Server-to-Server به شما ارسال شوند. مهم‌ترین رویداد payment.completed است.

POST https://shop.example.com/webhook HTTP/1.1
Content-Type: application/json
X-ZarGate-Signature: sha256=9f1d...e7

{
  "event": "payment.completed",
  "transactionId": "ZG-7F3A9C2E",
  "amount": 500000,
  "currency": "IRR",
  "gatewayTransactionId": "100200300",
  "timestamp": "2026-05-29T12:05:11Z"
}

تأیید امضای HMAC-SHA256

هر درخواست وب‌هوک شامل هدر X-ZarGate-Signature است. این امضا با الگوریتم HMAC-SHA256 روی بدنهٔ خام درخواست و با کلید مخفی وب‌هوک شما محاسبه می‌شود. برای جلوگیری از جعل، امضا را در سمت سرور بازتولید و مقایسه کنید:

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret)
          .update(rawBody, "utf8")
          .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}

پس از تأیید امضا، پاسخ 200 OK بازگردانید تا ارسال مجدد متوقف شود.

در صورت بروز خطا، پاسخ با کد وضعیت HTTP مناسب و بدنهٔ JSON زیر بازمی‌گردد:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is invalid or missing"
  }
}