برای استفاده از این درگاه، ابتدا باید در پنل مدیریت اسرار نهان برای کسب‌وکار شما یک «دامنه» ثبت شود. پس از ثبت، یک merchant_id اختصاصی در اختیار شما قرار می‌گیرد که در تمام درخواست‌های زیر باید ارسال شود. مبلغ در تمام endpointها به تومان است.

برای شروع یک پرداخت، درخواست زیر را از سمت سرور خودتان ارسال کنید:

POST https://asrarnahan.ir/api/gateway/payment/request

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

curl -X POST https://asrarnahan.ir/api/gateway/payment/request \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "MERCHANT_ID",
    "amount": 250000,
    "description": "خرید اشتراک",
    "mobile": "09120000000",
    "callback_url": "https://your-site.com/payment/callback?order_id=123"
  }'

نمونه پاسخ موفق (HTTP 201):

{
  "authority": "A00000000000000000000000000000wwOGYpd",
  "pay_url": "https://asrarnahan.ir/pay/A00000000000000000000000000000wwOGYpd"
}

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

1. سایت شما درخواست پرداخت را می‌سازد و کاربر را به pay_url می‌فرستد.
2. کاربر روی صفحه واقعی زرین‌پال، پرداخت را انجام می‌دهد.
3. زرین‌پال نتیجه را به اسرار نهان برمی‌گرداند و ما آن را نزد زرین‌پال Verify می‌کنیم.
4. مرورگر کاربر به همان callback_urlای که در مرحله ۱ داده بودید ریدایرکت می‌شود، با query paramهای authority، status و ref_id.
5. هم‌زمان یک درخواست POST (وب‌هوک) با همین اطلاعات مستقیم به همان callback_url ارسال می‌شود؛ برای اطمینان بیشتر، به وب‌هوک هم اعتماد کنید نه فقط ریدایرکت مرورگر.

نمونه ریدایرکت/وب‌هوک:

GET https://your-site.com/payment/callback?order_id=123&authority=A00...&status=paid&ref_id=123456

POST https://your-site.com/payment/callback
{
  "authority": "A00000000000000000000000000000wwOGYpd",
  "status": "paid",
  "amount": 250000,
  "ref_id": "123456"
}

برای اطمینان از وضعیت نهایی یک تراکنش (مثلا اگر وب‌هوک به هر دلیلی دریافت نشد)، می‌توانید در هر زمان این endpoint را صدا بزنید:

POST https://asrarnahan.ir/api/gateway/payment/verify

curl -X POST https://asrarnahan.ir/api/gateway/payment/verify \
  -H "Content-Type: application/json" \
  -d '{ "merchant_id": "MERCHANT_ID", "authority": "A00000000000000000000000000000wwOGYpd" }'

نمونه پاسخ:

{
  "status": "paid",
  "amount": 250000,
  "authority": "A00000000000000000000000000000wwOGYpd",
  "ref_id": "123456"
}

در تمام خطاها بدنه پاسخ به شکل { "error": "..." } است.

• مبلغ همیشه به تومان است، نه ریال.
• callback_url باید یک آدرس معتبر و در دسترس (http/https) باشد.
• هر authority فقط یک‌بار پردازش می‌شود؛ درخواست‌های تکراری همان نتیجه قبلی را برمی‌گردانند.
• برای دریافت merchant_id، از طریق راه‌های تماس با ما درخواست بدهید.