اتصال فروشگاه اینترنتی به نفیس پی

۱نمای کلی روند

1. مشتری در صفحه‌ی پرداخت فروشگاه شما «خرید اعتباری با نفیس پی» را انتخاب می‌کند.
2. سرور فروشگاه یک پرداخت در نفیس پی می‌سازد و یک آدرس هدایت (redirect) می‌گیرد.
3. مشتری به صفحه‌ی پرداخت لندتک (ارائه‌دهنده‌ی اعتبار) هدایت می‌شود و خرید را با اعتبار خود تأیید می‌کند.
4. لندتک مشتری را به نفیس پی برمی‌گرداند و نفیس پی پرداخت را سمت سرور با لندتک تأیید (verify) می‌کند.
5. سرور فروشگاه وضعیت پرداخت را از نفیس پی استعلام می‌کند و فقط در وضعیت موفق، سفارش را نهایی می‌کند.
6. در صورت لغو سفارش، برگشت کامل وجه در مهلت مجاز درخواست می‌شود.

۲احراز هویت

کلید وب‌سرویس (API key) پس از تأیید و امضای قرارداد پذیرندگی، از پنل پذیرنده صادر می‌شود. به‌زودی — صدور کلید در پنل هنوز فعال نیست و تا آن زمان کلید از طریق کارشناس نفیس پی هماهنگ می‌شود.

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

قالب نهایی هدر احراز هویت هم‌زمان با انتشار وب‌سرویس اعلام می‌شود.

۳ساخت پرداخت

برای هر سفارش یک پرداخت بسازید. مبلغ به ریال و عدد صحیح است.

POST https://api.nafispay.com/v1/payments   (پیش‌نمایش)

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

{
  "paymentId": "ORDER-10045",
  "amountRial": 125000000,
  "customer": {
    "mobile": "09120000000",
    "nationalId": "0000000000"
  },
  "items": [
    { "name": "گوشی موبایل", "count": 1, "amountRial": 125000000 }
  ]
}

نمونه‌ی پاسخ

{
  "paymentId": "ORDER-10045",
  "redirect": {
    "url": "REDIRECT_URL",
    "method": "GET"
  },
  "reused": false
}

۴هدایت مشتری و بازگشت (callback)

• مشتری را به redirect.url بفرستید. اگر redirect.method برابر POST بود، فیلدهای redirect.formFields را در یک فرم خودکار (auto-submit) به همان آدرس ارسال کنید.
• پس از پرداخت یا انصراف، لندتک مشتری را به آدرس بازگشت نفیس پی برمی‌گرداند؛ نفیس پی همان لحظه پرداخت را سمت سرور تأیید می‌کند و صفحه‌ی نتیجه را به مشتری نشان می‌دهد.
• پارامترهای آدرس بازگشت را هرگز به‌عنوان نشانه‌ی موفقیت نپذیرید؛ همیشه وضعیت را از سرور استعلام کنید (بخش ۵).
• بازگشت مستقیم مشتری به آدرس دلخواه فروشگاه و اعلان سرور‌به‌سرور (webhook): به‌زودی.

۵تأیید پرداخت

تأیید نهایی با لندتک را نفیس پی سمت سرور انجام می‌دهد. سرور شما فقط وضعیت را استعلام می‌کند:

GET https://api.nafispay.com/v1/payments/ORDER-10045   (پیش‌نمایش)

{
  "paymentId": "ORDER-10045",
  "state": "VERIFIED",
  "outcome": "success"
}

• سفارش را فقط وقتی نهایی کنید که outcome برابر success باشد.
• در pending (مثلاً PAID_UNVERIFIED) سفارش را باز نگه دارید و دوباره استعلام کنید؛ نفیس پی وضعیت را با لندتک همگام می‌کند.
• در review پرداخت برای بررسی به پشتیبانی نفیس پی ارجاع شده است؛ آن را موفق یا ناموفق فرض نکنید.

۶برگشت وجه

POST https://api.nafispay.com/v1/payments/ORDER-10045/refund   (پیش‌نمایش)

• فقط برگشت کامل مبلغ پشتیبانی می‌شود؛ برگشت بخشی از مبلغ فعلاً امکان‌پذیر نیست.
• برگشت فقط برای پرداخت موفق و در مهلت مجاز هر لندتک ممکن است (بسته به لندتک، چند روز پس از خرید یا تا پیش از تسویه). پس از پایان مهلت، درخواست رد می‌شود.
• برای یک پرداخت هم‌زمان فقط یک عملیات اجرا می‌شود؛ درخواست موازی با خطای تداخل رد می‌شود.

۷وضعیت‌ها و خطاها

خطاها

{ "error": "validation", "message": "شماره موبایل معتبر نیست" }

پیام خطاها فارسی و قابل نمایش به کاربر است.

۸نکات آزمایش

• محیط آزمایشی (sandbox) عمومی و کلید آزمایشی: به‌زودی. تا آن زمان آزمایش اتصال با هماهنگی کارشناس نفیس پی انجام می‌شود.
• با مبلغ کم آزمایش کنید و برای هر تلاش یک paymentId تازه بسازید.
• سناریوهای انصراف مشتری، بستن صفحه پیش از بازگشت، و تکرار درخواست ساخت با همان شناسه را هم بیازمایید.
• موفقیت را فقط از استعلام سمت سرور بپذیرید، نه از صفحه‌ی بازگشت.
• پرسش یا مشکل: info@nafispay.com · ۰۹۳۷۰۵۶۹۴۹۴