راهنمای یکپارچه‌سازی

ثبت‌نام

در پنل بازرگان حساب کاربری بسازید و فرایند احراز هویت (KYC) را تکمیل کنید.

افزودن درگاه و کلیدها

در بخش «درگاه‌ها» یکی از درگاه‌های بانکی پشتیبانی‌شده (مانند زرین‌پال، آسان‌پرداخت، سداد و…) را اضافه کرده و کلیدها/شناسه پذیرنده آن را وارد کنید. این اطلاعات به‌صورت رمزنگاری‌شده ذخیره می‌شوند.

ساخت کلید API

در بخش «کلیدهای API» یک کلید زنده (sk_live_…) بسازید. این کلید را فقط در سمت سرور نگه دارید و هرگز در کد سمت کلاینت منتشر نکنید.

ایجاد پرداخت

یک درخواست به نقطه پایانی ایجاد پرداخت بفرستید:

curl -X POST https://api.zargate.ir/api/v1/payments \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "IRR",
    "orderId": "ORDER-1024",
    "callbackUrl": "https://shop.example.com/callback"
  }'

همین درخواست با fetch در جاوااسکریپت:

const res = await fetch("https://api.zargate.ir/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 500000,
    currency: "IRR",
    orderId: "ORDER-1024",
    callbackUrl: "https://shop.example.com/callback",
  }),
});

const payment = await res.json();
// payment.trackingCode, payment.paymentUrl

هدایت به صفحه پرداخت

کاربر را به آدرس صفحه پرداخت میزبانی‌شده هدایت کنید:

// با استفاده از پاسخ مرحله قبل
res.redirect(payment.paymentUrl);
// یا به‌صورت دستی:
// https://portal.zargate.ir/pay/{trackingCode}

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

دریافت وب‌هوک

برای اطمینان از ثبت پرداخت حتی اگر کاربر صفحه را ببندد، یک وب‌هوک تنظیم کنید و امضای X-ZarGate-Signature را بررسی کنید:

app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-zargate-signature"];
  if (!verify(req.body, sig, process.env.ZG_WEBHOOK_SECRET)) {
    return res.status(400).end();
  }
  const evt = JSON.parse(req.body.toString());
  if (evt.event === "payment.completed") {
    // سفارش را نهایی کنید
  }
  res.status(200).end();
});