AAJAXPAY

توسعه‌دهندگان / درگاه سایت

راهنمای اتصال پرداخت

قرارداد اتصال سایت، از ایجاد سفارش تا استعلام نتیجه.

بازگشت به پرتال
این صفحه فقط نمونهٔ محلی می‌سازد. کلید آزمایشی شبیه‌ساز را باز می‌کند. برای پرداخت بانکی، درگاه واقعی همان سایت باید تأیید و به پایانهٔ آماده تخصیص داده شود. دسترسی به قابلیت، به تنظیمات سرویس، تأیید پرونده و مسیر مجاز نیاز دارد؛ پاسخ 503 به‌معنای در دسترس نبودن قابلیت است.

نمونه‌ساز محلی

مقادیر آموزشی وارد کنید. کلید واقعی یا اطلاعات حساس در این صفحه لازم نیست.

POST /api/v1/merchant/payments
{
  "merchantOrderId": "order-100",
  "amountToman": "10000",
  "callbackUrl": "https://shop.example/paid",
  "expiresInMinutes": 15,
  "description": "پرداخت سفارش"
}

هدرهای اجباری: X-AjaxPay-Api-Key و Idempotency-Key. تکرار کلید با بدنهٔ متفاوت، پاسخ تعارض می‌دهد.

نمونهٔ کد سرور فروشگاه

این کد آموزشی اجرا نمی‌شود؛ ذخیرهٔ سفارش و تنظیم مبدأها بر عهدهٔ سرور فروشگاه است.

// فقط در سرور فروشگاه؛ کلید را وارد مرورگر یا URL نکنید.
// paymentRequestKey را پیش از اولین ارسال در سفارش ذخیره کنید.
// در retry همان کلید و همان بدنه را دوباره بفرستید.
const idempotencyKey = savedOrder.paymentRequestKey;
const response = await fetch(
  process.env.AJAXPAY_API_ORIGIN + '/api/v1/merchant/payments',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-AjaxPay-Api-Key': process.env.AJAXPAY_API_KEY,
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
  "merchantOrderId": "order-100",
  "amountToman": "10000",
  "callbackUrl": "https://shop.example/paid",
  "expiresInMinutes": 15,
  "description": "پرداخت سفارش"
})
  }
);
const result = await response.json();
if (!response.ok || !result.isSuccess) throw new Error('Payment creation failed');
// paymentId را کنار سفارش خود ذخیره کنید.
const landing = new URL(process.env.PUBLIC_LANDING_ORIGIN);
const checkout = new URL(result.data.publicCheckoutUrl);
const expectedPath = (result.data.environment === 'Live' ? '/live' : '') + '/checkout/';
if (checkout.origin !== landing.origin || checkout.protocol !== 'https:' ||
    checkout.username || checkout.password || checkout.search || checkout.hash ||
    !checkout.pathname.startsWith(expectedPath) ||
    !/^[a-f0-9]{64}$/.test(checkout.pathname.slice(expectedPath.length))) {
  throw new Error('Invalid checkout URL');
}
const redirectUrl = checkout.href;
// فقط redirectUrl را به مرورگر بدهید؛ بدون کلید API.

قالب پاسخ ایجاد درخواست

صرفاً شکل قرارداد با مقادیر جایگزین؛ پاسخ واقعی سرویس یا تأیید پرداخت نیست. کارمزد و خالص را سرور مطابق تعرفهٔ همین کسب‌وکار محاسبه می‌کند.

{
  "isSuccess": true,
  "data": {
    "paymentId": "<payment-guid>",
    "merchantOrderId": "<merchantOrderId>",
    "amountToman": "<exact-toman-string>",
    "feeToman": "<server-calculated-fee>",
    "netToman": "<server-calculated-net>",
    "status": "AwaitingPayer",
    "expiresAt": "<UTC-ISO-8601>",
    "checkoutUrl": "/api/v1/sandbox/checkout/<64-character-token>",
    "publicCheckoutUrl": "https://landing.example/checkout/<64-character-token>",
    "callbackUrl": "<approved-callbackUrl>",
    "environment": "Sandbox",
    "creditStatus": "SandboxNoCredit",
    "paymentMethod": "Bank",
    "voucherReceipt": null,
    "voucherCredit": null,
    "voucherRefund": null
  }
}

استعلام و تأیید نتیجه

GET /api/v1/merchant/payments/{paymentId}

از سرور خود و با هدر X-AjaxPay-Api-Key همان سایت استعلام کنید. شکل دادهٔ پاسخ همان قرارداد بالا است. شناسه، مرجع سفارش و مبلغ را با سفارش ذخیره‌شده تطبیق دهید؛ تنها Succeeded نتیجهٔ موفق است. وضعیت‌هایی مانند Verifying و ReviewRequired قطعی نیستند.

موفقیت پرداخت با آزادسازی اعتبار یا تسویه بانکی یکسان نیست. مقدار SandboxNoCredit به‌معنای اعتبار واقعی نیست. اعلان سرور نیز باید با امضای معتبر و پردازش تکرارپذیر بررسی شود؛ جزئیات ارسال را در تب اعلان‌های سرور ببینید.