راه‌اندازی درگاه پرداخت به‌پرداخت ملت ووکامرس

درگاه به‌پرداخت ملت جم پک، فروشگاه ووکامرسی را مستقیماً به دروازه پرداخت اینترنتی به‌پرداخت بانک ملت متصل می‌کند. فروشگاه ابتدا درخواست پرداخت می‌فرستد و شناسه RefId را دریافت می‌کند. مشتری با این شناسه به صفحه بانک می‌رود. پس از بازگشت، جم پک تراکنش را تأیید (Verify) و سپس تسویه آن را نهایی (Settle) می‌کند.

پرداخت ملت چند مرحله دارد که باید به‌ترتیب کامل شوند:

1. دریافت RefId با bpPayRequest؛
2. انتقال فرم‌محور مشتری به صفحه پرداخت؛
3. دریافت Callback و تطبیق دقیق آن با سفارش؛
4. تأیید تراکنش با bpVerifyRequest؛
5. نهایی‌کردن تسویه با bpSettleRequest؛
6. ثبت SaleReferenceId و نتیجه تسویه در سفارش.

بازگشت مشتری از بانک یا حتی موفق‌بودن پاسخ اولیه Callback، به‌تنهایی اثبات نمی‌کند که مبلغ برای پذیرنده تسویه شده است. Verify و Settle دو مرحله جدا هستند و هر دو باید با دقت بررسی شوند.

این قابلیت در سطح Pro ارائه می‌شود و برای آغاز پرداخت جدید به لایسنس معتبر جم پک نیاز دارد.

این راهنما چه مواردی را پوشش می‌دهد؟

• دریافت و آماده‌سازی پایانه اینترنتی به‌پرداخت ملت؛
• ثبت IP خروجی و دامنه صحیح فروشگاه؛
• واردکردن Terminal ID، نام کاربری و رمز پذیرنده؛
• تنظیم عنوان، توضیحات و زبان صفحه پرداخت؛
• ارسال اختیاری شماره موبایل مشتری؛
• آشنایی با RefId، SaleOrderId و SaleReferenceId؛
• درک تفاوت Pay Request، Callback، Verify و Settle؛
• کنترل مبلغ ریالی تراکنش؛
• رفتار سفارش در Verify نامشخص یا Settle ناموفق؛
• بازپرداخت کامل یا جزئی از داخل ووکامرس؛
• شناخت محدودیت Reverse در نسخه بررسی‌شده؛
• کدهای خطای مهم و روش عیب‌یابی؛
• آزمون کامل پیش از فعال‌سازی عمومی.

برای الزامات عمومی HTTPS، کش، وضعیت سفارش و اصول آزمون، ابتدا تنظیمات مشترک درگاه‌های پرداخت ووکامرس را مطالعه کنید.

دریافت پایانه از به‌پرداخت ملت

شرایط پذیرندگی، مدارک و مراحل فعال‌سازی ممکن است تغییر کنند. اطلاعات جاری را از وب‌سایت و پشتیبانی رسمی به‌پرداخت ملت دریافت کنید. روند کلی معمولاً شامل این مراحل است:

1. درخواست پایانه پرداخت اینترنتی را ثبت کنید.
2. اطلاعات هویتی، مالیاتی، بانکی و مدارک کسب‌وکار را تکمیل کنید.
3. دامنه فروشگاه و اطلاعات فنی موردنیاز را اعلام کنید.
4. قراردادها و تعهدنامه‌های پذیرندگی را تکمیل کنید.
5. Terminal ID، نام کاربری و رمز را دریافت کنید.
6. IP خروجی سرور و دامنه Callback را برای پایانه ثبت کنید.
7. فعال‌بودن سرویس‌های Pay، Verify، Settle و در صورت نیاز Refund را پیگیری کنید.
8. پیش از فروش واقعی، یک پرداخت کم‌مبلغ را از ابتدا تا ثبت سفارش آزمایش کنید.

Terminal ID را با شماره پذیرنده، شماره حساب، شناسه شبا یا شماره پیگیری تراکنش اشتباه نگیرید. نام کاربری و رمز نیز باید متعلق به همان Terminal ID باشند.

IP خروجی و دامنه ثبت‌شده

به‌پرداخت ملت می‌تواند درخواست را بر اساس IP سرور و دامنه پذیرنده کنترل کند. IP موردنیاز لزوماً IP نمایش‌داده‌شده در DNS یا IP ورودی CDN نیست؛ باید IP عمومی‌ای را اعلام کنید که درخواست‌های خروجی PHP از طریق آن به وب‌سرویس بانک می‌رسند.

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

• IP عمومی خروجی PHP یا وب‌سرور؛
• امکان اتصال HTTPS به bpm.shaparak.ir؛
• نبود محدودیت فایروال برای SOAP و درخواست‌های POST؛
• صحت DNS Resolver و گواهی‌های CA روی سرور.

اگر هاست، دیتاسنتر، NAT، Proxy یا مسیر خروجی تغییر کند، IP نیز ممکن است عوض شود. پس از هر مهاجرت، درخواست پرداخت و Callback را دوباره آزمایش کنید.

دامنه Callback از آدرس خود سایت ساخته می‌شود و فیلد جداگانه‌ای برای واردکردن آن در تنظیمات افزونه وجود ندارد. دامنه نهایی وردپرس باید با دامنه ثبت‌شده برای پایانه هماهنگ باشد. جابه‌جایی خودکار میان www و بدون www، تغییر HTTP به HTTPS یا Redirectهای چندمرحله‌ای را نیز بررسی کنید.

ورود به تنظیمات به‌پرداخت ملت

برای پیکربندی درگاه:

1. وارد پیشخوان وردپرس شوید.
2. از منوی جم پک، «درگاه‌های پرداخت» را انتخاب کنید.
3. پنل «ملت» یا «به‌پرداخت ملت» را باز کنید.
4. سه گروه تنظیمات پایه، حساب ملت و عملیات پرداخت را تکمیل کنید.
5. تغییرات را ذخیره کنید.

نشانی صفحه تنظیمات:

/wp-admin/admin.php?page=gempack#payment-gateways

وضعیت فعال‌سازی با روش پرداخت مربوط در «ووکامرس ← پیکربندی ← پرداخت‌ها» همگام می‌شود. برای ویرایش همه گزینه‌ها، صفحه درگاه‌های پرداخت جم پک را مرجع اصلی قرار دهید.

تنظیمات پایه

فعال‌سازی درگاه ملت

این گزینه، نمایش ملت در تسویه‌حساب را کنترل می‌کند. پیش از فعال‌کردن آن برای مشتریان، اطلاعات اتصال، IP و دامنه را کامل کنید و یک تراکنش کنترل‌شده انجام دهید.

اگر Terminal ID خالی باشد، درگاه آماده دریافت پرداخت نخواهد بود و هشدار مربوط به اطلاعات ضروری نمایش داده می‌شود.

عنوان درگاه

عنوان در Checkout به مشتری نمایش داده می‌شود. مقدار پیش‌فرض نسخه بررسی‌شده «بانک ملت» است.

نمونه پیشنهادی:

پرداخت آنلاین با بانک ملت

اگر چند درگاه بانکی دارید، نام بانک یا شرکت پرداخت را در عنوان حفظ کنید تا انتخاب‌ها برای مشتری روشن باشند.

توضیحات درگاه

این متن زیر عنوان روش پرداخت نمایش داده می‌شود. مقدار پیشنهادی:

پرداخت امن سفارش با کارت‌های عضو شبکه شتاب از طریق درگاه به‌پرداخت ملت

Terminal ID، نام کاربری، IP یا اطلاعات قرارداد را در توضیح قابل‌مشاهده Checkout قرار ندهید.

تنظیمات حساب ملت

Terminal ID

شماره پایانه‌ای را وارد کنید که به‌پرداخت برای دامنه فروشگاه صادر کرده است. این فیلد ضروری است و در فراخوانی‌های Pay، Verify، Settle و Refund استفاده می‌شود.

هنگام ثبت مقدار:

• از Terminal ID همان محیط استفاده کنید؛
• فاصله ابتدا و انتها را حذف کنید؛
• شماره پذیرنده یا حساب را جایگزین آن نکنید؛
• مطمئن شوید IP و دامنه روی همان پایانه ثبت شده‌اند؛
• مقدار را در اسکرین‌شات و گزارش عمومی محو کنید.

نام کاربری

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

رمز عبور

رمز پذیرنده را در فیلد Password ثبت کنید. این رمز با رمز ورود وردپرس، پنل بانک یا حساب مشتری تفاوت دارد.

پس از تغییر رمز در سمت به‌پرداخت، مقدار ذخیره‌شده در سایت را نیز بروزرسانی و یک پرداخت جدید آزمایش کنید. نام کاربری و رمز پذیرنده را در تیکت عمومی، تصویر آموزشی یا گزارش خطا نشان ندهید.

تنظیمات عملیات پرداخت

زبان صفحه پرداخت

دو انتخاب در نسخه بررسی‌شده وجود دارد:

• فارسی؛
• انگلیسی.

این گزینه آدرس صفحه انتقال بانکی را تغییر می‌دهد و زبان Checkout خود فروشگاه را عوض نمی‌کند. برای فروشگاه فارسی، مقدار فارسی انتخاب طبیعی‌تری است.

ارسال شماره موبایل مشتری

این گزینه به‌صورت پیش‌فرض فعال است. اگر شماره صورتحساب معتبر باشد، همراه فرم انتقال با نام MobileNo ارسال می‌شود تا درگاه بتواند قابلیت‌هایی مانند پیشنهاد کارت‌های قبلاً استفاده‌شده را ارائه کند.

شماره‌های زیر به قالب موردنیاز درگاه تبدیل می‌شوند:

09121234567
989121234567
00989121234567

خروجی برای به‌پرداخت به این قالب تبدیل می‌شود:

989121234567

اگر شماره پس از حذف نویسه‌های اضافی، ده رقم و شروع‌شونده با 9 نباشد، برای درگاه ارسال نمی‌شود.

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

پیام پرداخت موفق

در متن موفق می‌توانید از جای‌نگهدار زیر استفاده کنید:

{transaction_id}

این مقدار با SaleReferenceId تأییدشده جایگزین می‌شود.

نمونه پیشنهادی:

پرداخت سفارش با موفقیت تأیید شد. شماره پیگیری ملت: {transaction_id}

پیام پرداخت ناموفق

در متن ناموفق می‌توانید از این جای‌نگهدار استفاده کنید:

{fault}

نمونه پیشنهادی:

پرداخت تکمیل نشد: {fault} لطفاً دوباره تلاش کنید یا با پشتیبانی فروشگاه تماس بگیرید.

پیام مشتری را کوتاه و قابل‌اقدام نگه دارید. کد فنی، اعتبارنامه، پاسخ SOAP یا جزئیات زیرساخت نباید در متن عمومی نمایش داده شوند.

نشانی Callback

Callback درگاه به‌صورت خودکار از نشانی سایت و Endpoint ووکامرس ساخته می‌شود. ساختار آن مشابه نمونه زیر است:

https://example.com/?wc-api=aio_wc_mellat&wc_order=123

بسته به ساختار پیوندهای یکتا، شکل ظاهری URL می‌تواند متفاوت باشد. این نشانی را به‌صورت دستی در تنظیمات جم پک وارد نمی‌کنید.

برای سالم‌ماندن Callback:

• دامنه نهایی باید با دامنه ثبت‌شده پایانه یکسان باشد؛
• HTTPS معتبر باشد؛
• Query String شامل wc_order حذف نشود؛
• مسیر پشت ورود اجباری یا Basic Authentication نباشد؛
• WAF، افزونه امنیتی یا محدودیت جغرافیایی درخواست بانک را مسدود نکند؛
• کش صفحه روی Endpoint اعمال نشود؛
• Redirectها داده POST را از بین نبرند.

بانک از بیرون سایت به مسیر بازگشت درخواست می‌فرستد؛ بنابراین ورود مشتری یا توکن امنیتی فرم (Nonce) برای اجرای آن لازم نیست. درگاه با تطبیق سفارش و شناسه‌ها و تأیید تراکنش در سرور، نتیجه را بررسی می‌کند.

واحد پول و مبلغ ارسالی

به‌پرداخت مبلغ را به ریال دریافت می‌کند. جم پک مبلغ سفارش را پیش از ارسال به ریال تبدیل و همان مقدار را در متای سفارش ذخیره می‌کند.

اگر واحد فروشگاه تومان باشد، تبدیل واحد باید در آزمون واقعی کنترل شود. برای مثال، سفارشی با مبلغ ۱۰۰٬۰۰۰ تومان باید در صفحه درگاه معادل ۱٬۰۰۰٬۰۰۰ ریال نمایش داده شود.

پس از تغییر واحد پول، افزونه چندارزی، مالیات، تخفیف یا محاسبه ارسال، این چهار مقدار را با هم مقایسه کنید:

1. جمع نهایی Checkout؛
2. مبلغ صفحه پرداخت؛
3. مبلغ ثبت‌شده در سفارش؛
4. مبلغ پنل به‌پرداخت.

فرایند واقعی پرداخت در جم پک

۱. ساخت درخواست Pay

پس از ثبت سفارش، افزونه عملیات bpPayRequest را با این داده‌های اصلی اجرا می‌کند:

• Terminal ID؛
• نام کاربری و رمز؛
• Order ID یکتای درخواست؛
• مبلغ ریالی؛
• تاریخ و ساعت محلی سایت؛
• توضیح کوتاه سفارش؛
• Callback خودکار؛
• Payer ID با مقدار 0.

Order ID ارسالی به بانک لزوماً شماره سفارش ووکامرس نیست. ملت برای هر درخواست پرداخت یک شناسه یکتا می‌خواهد و مشتری ممکن است برای یک سفارش چند بار تلاش کند. جم پک برای هر درخواست، شناسه‌ای تازه از یک شمارنده افزایشی مبتنی بر زمان می‌سازد و ارتباط آن را با سفارش ووکامرس ذخیره می‌کند.

۲. دریافت RefId

پاسخ موفق bpPayRequest به‌شکل زیر است:

0,RefId

کد 0 یعنی درخواست پذیرفته شده و بخش دوم، RefId لازم برای ورود مشتری به صفحه پرداخت است.

RefId به بزرگی و کوچکی حروف حساس است و باید بدون تغییر استفاده شود. این شناسه را با SaleReferenceId نهایی یا شماره سفارش اشتباه نگیرید.

جم پک این موارد را روی سفارش نگه می‌دارد:

• RefId؛
• Order ID یکتای ملت؛
• مبلغ ریالی مورد انتظار.

اگر کد پاسخ صفر نباشد یا RefId خالی باشد، مشتری به صفحه بانک فرستاده نمی‌شود و علت قابل‌شناسایی در سفارش ثبت می‌گردد.

۳. انتقال فرم‌محور به درگاه

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

علت استفاده از فرم این است که به‌پرداخت می‌تواند Referer مرورگر را با دامنه ثبت‌شده پذیرنده تطبیق دهد. Redirect مستقیم سمت سرور Referer مورد انتظار را ایجاد نمی‌کند.

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

صفحه رسید و فرم انتقال را از کش و بهینه‌سازی‌هایی که HTML را تغییر می‌دهند یا اسکریپت‌ها را حذف می‌کنند خارج کنید.

۴. بازگشت از بانک

به‌پرداخت می‌تواند این داده‌های اصلی را در Callback برگرداند:

• ResCode؛
• RefId؛
• SaleOrderId؛
• SaleReferenceId؛
• CardHolderPan؛
• FinalAmount.

وجود این داده‌ها به‌تنهایی پرداخت را قطعی نمی‌کند. ابتدا سفارش پیدا و سپس اطلاعات بازگشتی با داده‌های ذخیره‌شده تطبیق داده می‌شوند.

۵. تطبیق امنیتی Callback

پیش از Verify، افزونه این کنترل‌ها را انجام می‌دهد:

1. سفارش از wc_order یا SaleOrderId پیدا شود؛
2. سفارش از قبل پرداخت‌شده نباشد؛
3. RefId دقیقاً با مقدار ذخیره‌شده همان سفارش برابر باشد؛
4. SaleOrderId دقیقاً با Order ID یکتای همان تلاش برابر باشد؛
5. ResCode برابر 0 باشد؛
6. SaleReferenceId خالی نباشد؛
7. همان SaleReferenceId قبلاً برای سفارش دیگری استفاده نشده باشد.

اگر RefId یا SaleOrderId تطبیق نداشته باشند، Verify اجرا نمی‌شود. این رفتار از نسبت‌دادن نتیجه یک تراکنش به سفارش دیگر جلوگیری می‌کند.

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

۶. Verify تراکنش

پس از عبور از کنترل‌های Callback، bpVerifyRequest اجرا می‌شود. دو پاسخ زیر در نسخه بررسی‌شده موفق در نظر گرفته می‌شوند:

کد	معنی عملی
0	تراکنش تأیید شد
43	تراکنش قبلاً تأیید شده است

کد 43 در اجرای تکراری می‌تواند نتیجه‌ای قابل‌قبول باشد و نباید صرفاً به‌دلیل تکرار، سفارش معتبر را ناموفق کرد.

تأیید تراکنش باید در مهلت به‌پرداخت انجام شود. راهنمای فنی مبنای این نسخه، حداکثر ۲۰ دقیقه را تعیین کرده است. تراکنش تأییدنشده ممکن است پس از این مهلت خودکار برگشت بخورد.

اگر Verify پاسخ ندهد، سفارش در وضعیت «در انتظار بررسی» (on-hold) قرار می‌گیرد. ممکن است مشتری پرداخت کرده باشد، اما نتیجه هنوز مشخص نباشد. پیش از تحویل کالا یا دسترسی، تراکنش را در پنل به‌پرداخت بررسی کنید.

۷. کنترل مبلغ

پس از تأیید تراکنش و پیش از تسویه، اگر FinalAmount در پاسخ وجود داشته باشد و عددی باشد، با مبلغ ریالی ذخیره‌شده سفارش مقایسه می‌شود.

اگر دو مبلغ متفاوت باشند:

• سفارش تکمیل نمی‌شود؛
• سفارش به on-hold می‌رود؛
• SaleReferenceId و مبلغ گزارش‌شده ذخیره می‌شوند؛
• Settle اجرا نمی‌شود؛
• Reverse نیز به‌صورت خودکار اجرا نمی‌شود؛
• مدیر باید وضعیت را از پنل به‌پرداخت بررسی کند.

اگر FinalAmount در Callback وجود نداشته باشد، نسخه بررسی‌شده پرداخت را فقط به‌دلیل نبود این فیلد متوقف نمی‌کند. در این حالت، تطبیق RefId و SaleOrderId اتصال تراکنش به سفارش را اثبات می‌کند، اما مبلغ بازگشتی مستقلی برای مقایسه وجود ندارد.

۸. Settle تراکنش

پس از Verify و کنترل مبلغ، bpSettleRequest اجرا می‌شود. Settle مرحله‌ای است که انتقال مبلغ به حساب پذیرنده را نهایی می‌کند؛ Verify به‌تنهایی برای واریز کافی نیست.

پاسخ‌های زیر موفق محسوب می‌شوند:

کد	معنی عملی
0	درخواست تسویه پذیرفته شد
45	تراکنش قبلاً تسویه شده است

پس از تأیید پرداخت، SaleReferenceId به‌عنوان Transaction ID ووکامرس ثبت می‌شود. شماره کارت ماسک‌شده و FinalAmount نیز در صورت حضور ذخیره می‌شوند.

۹. اگر Settle ناموفق باشد

شکست Settle با پرداخت ناموفق یکسان نیست. در این حالت، مشتری پرداخت کرده و Verify انجام شده، اما مبلغ هنوز برای پذیرنده نهایی نشده است.

نسخه بررسی‌شده:

• شناسه تراکنش و اطلاعات پرداخت را روی سفارش ثبت می‌کند؛
• عملیات استاندارد payment_complete() ووکامرس را اجرا می‌کند؛
• نتیجه Settle را با مقدار ناموفق ذخیره می‌کند؛
• یادداشت هشدار به سفارش می‌افزاید؛
• سپس وضعیت سفارش را به on-hold تغییر می‌دهد تا از ارسال یا تحویل جلوگیری شود.

در این سناریو، موجودی ممکن است مطابق فرایند استاندارد پرداخت ووکامرس کاهش یافته باشد، اما سفارش نباید پردازش یا ارسال شود. ابتدا تراکنش را در پنل به‌پرداخت تسویه یا تعیین تکلیف و سپس وضعیت سفارش را به‌صورت آگاهانه تغییر دهید.

تفاوت شناسه‌ها

شناسه	کاربرد
شماره سفارش ووکامرس	شناسه سفارش داخل فروشگاه
Order ID ملت	شناسه یکتای هر تلاش پرداخت برای bpPayRequest
RefId	مجوز کوتاه‌عمر انتقال مشتری به صفحه پرداخت
SaleOrderId	Order ID ملت که در Callback برمی‌گردد
SaleReferenceId	شناسه نهایی تراکنش و Transaction ID سفارش

برای پشتیبانی، شماره سفارش ووکامرس و SaleReferenceId را همراه زمان و مبلغ نگه دارید. RefId و اعتبارنامه را در کانال عمومی منتشر نکنید.

Reverse در نسخه بررسی‌شده

Reverse با Refund تفاوت دارد. Reverse معمولاً برای برگرداندن یک تراکنش در بازه کوتاه تأیید و تسویه استفاده می‌شود؛ Refund بازپرداخت تراکنشی است که قبلاً تسویه شده است.

در نسخه ۱.۷۳.۱۱، درگاه ملت جم پک فراخوانی bpReversalRequest ندارد و Reverse را به‌صورت دستی یا خودکار از داخل افزونه اجرا نمی‌کند.

• در Verify بی‌پاسخ، سفارش on-hold می‌شود و وضعیت باید در پنل بررسی شود؛
• در مغایرت مبلغ، Settle و Reverse هر دو اجرا نمی‌شوند؛
• در شکست Settle، سفارش on-hold می‌شود تا مدیر تسویه را از سمت به‌پرداخت پیگیری کند؛
• تراکنش تأییدنشده می‌تواند طبق قواعد سرویس در بازه مربوط به‌صورت خودکار بازگردانده شود، اما این نتیجه باید از پنل پذیرنده کنترل شود.

برای پیگیری برگشت تراکنش در این وضعیت‌ها، از پنل یا پشتیبانی به‌پرداخت استفاده کنید؛ این نسخه Reverse را از داخل افزونه اجرا نمی‌کند.

بازپرداخت از ووکامرس

درگاه ملت در نسخه بررسی‌شده از Refund کامل و جزئی پشتیبانی می‌کند. درخواست با bpRefundRequest ارسال می‌شود و فقط برای تراکنشی قابل انجام است که SaleOrderId و SaleReferenceId آن روی سفارش ثبت شده باشند.

برای بازپرداخت:

1. وارد «ووکامرس ← سفارش‌ها» شوید.
2. سفارش پرداخت‌شده با ملت را باز کنید.
3. در بخش اقلام سفارش، «بازپرداخت» را انتخاب کنید.
4. مبلغ یا تعداد اقلام را تعیین کنید.
5. گزینه بازپرداخت از طریق درگاه ملت را انتخاب کنید.
6. نتیجه عملیات و یادداشت سفارش را بررسی کنید.
7. وضعیت نهایی را در پنل به‌پرداخت نیز کنترل کنید.

مبلغ بازپرداخت از واحد فروشگاه به ریال تبدیل می‌شود. هر درخواست Refund یک Order ID یکتای جدید می‌گیرد. دلیل متنی بازپرداخت در نسخه بررسی‌شده به API ملت ارسال نمی‌شود.

تنها پاسخ 0 موفق تلقی می‌شود. کدهای دیگر به‌صورت خطای مدیریتی بازگردانده می‌شوند. اگر فروش تسویه نشده باشد، کدهایی مانند 42 یا 46 می‌توانند نشان دهند تراکنش مناسب Refund نیست.

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

ارتباط SOAP و نیازمندی سرور

درخواست‌های پرداخت، تأیید، تسویه و بازپرداخت با پروتکل SOAP ارسال می‌شوند. جم پک ابتدا از افزونه PHP SOAP استفاده می‌کند. اگر SoapClient موجود نباشد، همان پیام SOAP را از طریق ابزار ارتباط HTTP وردپرس می‌فرستد.

در نتیجه نبود افزونه PHP SOAP لزوماً درگاه را از کار نمی‌اندازد؛ بااین‌حال، سرور باید بتواند:

• WSDL یا Endpoint به‌پرداخت را Resolve کند؛
• اتصال TLS معتبر بسازد؛
• درخواست POST خروجی ارسال کند؛
• پاسخ XML را بدون تغییر دریافت کند.

Timeout، خطای DNS، گواهی CA قدیمی یا مسدودبودن IP می‌تواند هر دو روش ارتباطی را مختل کند.

Checkout کلاسیک و بلوکی

درگاه از زیرساخت مشترک روش‌های پرداخت جم پک استفاده می‌کند و برای Checkout کلاسیک و Checkout بلوکی ووکامرس ثبت می‌شود. پس از هر تغییر قالب یا افزونه Checkout، این سناریوها را جداگانه آزمایش کنید:

• نمایش عنوان و توضیح درگاه؛
• انتخاب ملت و ایجاد سفارش؛
• ورود به صفحه رسید؛
• ارسال فرم به بانک؛
• بازگشت به Callback؛
• نمایش نتیجه و ثبت Transaction ID.

اگر افزونه‌ای چرخه استاندارد Checkout را به‌طور کامل جایگزین می‌کند، سازگاری آن نیازمند آزمون جداگانه است.

گزارش‌ها و اطلاعات سفارش

این درگاه در نسخه بررسی‌شده گزینه Debug و منبع گزارش اختصاصی در تنظیمات ندارد. اطلاعات اصلی عیب‌یابی در یادداشت‌ها و متای سفارش ثبت می‌شوند.

موارد قابل انتظار در سفارش:

• علت رد درخواست Pay؛
• شکست تطبیق RefId یا SaleOrderId؛
• تکراری‌بودن SaleReferenceId؛
• نتیجه ناموفق Verify؛
• Verify بی‌پاسخ و انتقال به on-hold؛
• مغایرت مبلغ و مقدارهای مورد انتظار و دریافت‌شده؛
• SaleReferenceId به‌عنوان Transaction ID؛
• شماره کارت ماسک‌شده در صورت دریافت؛
• نتیجه موفق یا ناموفق Settle؛
• نتیجه درخواست Refund.

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

کدهای خطای مهم

کد	مفهوم کاربردی	اقدام پیشنهادی
0	عملیات موفق	مرحله بعدی فرایند را ادامه دهید
11	شماره کارت نامعتبر	مشتری اطلاعات کارت را بررسی کند
12	موجودی کافی نیست	روش یا کارت دیگری استفاده شود
17	مشتری پرداخت را لغو کرده است	سفارش پرداخت‌نشده باقی بماند
18	کارت منقضی شده است	کارت دیگری استفاده شود
21	پذیرنده معتبر نیست	وضعیت قرارداد و پایانه بررسی شود
23	خطای امنیتی	IP، دامنه و اعتبارنامه بررسی شوند
24	اطلاعات پذیرنده معتبر نیست	Terminal ID، نام کاربری و رمز تطبیق داده شوند
25	مبلغ معتبر نیست	واحد پول و مبلغ ریالی بررسی شوند
31	پاسخ معتبر نیست	Callback و پاسخ سرویس بررسی شوند
32	قالب داده صحیح نیست	پارامترهای درخواست و نسخه سرویس بررسی شوند
34	خطای سیستمی	پس از بررسی وضعیت تراکنش دوباره تلاش شود
41	شماره درخواست تکراری است	پرداخت جدید با Order ID یکتا ساخته شود
42	تراکنش فروش پیدا نشد	شناسه‌ها و محیط پایانه بررسی شوند
43	تراکنش قبلاً Verify شده است	در مرحله Verify حالت موفق قابل‌قبول است
44	درخواست Verify پیدا نشد	ترتیب و شناسه عملیات بررسی شود
45	تراکنش قبلاً Settle شده است	در مرحله Settle حالت موفق قابل‌قبول است
46	تراکنش تسویه نشده است	وضعیت تراکنش در پنل بررسی شود
47	تسویه پیدا نشد	SaleReferenceId و سوابق پنل بررسی شوند
48	تراکنش Reverse و مبلغ بازگردانده شده است	سفارش تحویل نشود
51	تراکنش تکراری است	سفارش‌ها و مرجع تراکنش بررسی شوند
54	تراکنش مرجع وجود ندارد	شناسه‌ها و پایانه کنترل شوند
61	خطا در تسویه	سفارش on-hold بماند و پنل بررسی شود
62	Callback خارج از دامنه ثبت‌شده است	دامنه و Redirectها اصلاح شوند
421	IP معتبر نیست	IP خروجی واقعی نزد به‌پرداخت ثبت شود

کدها و شرح سرویس می‌توانند در نسخه‌های بعدی تغییر کنند. پیام نسخه جاری افزونه و مستند فنی پایانه را مرجع نهایی قرار دهید.

آزمون کامل پیش از انتشار

پرداخت موفق

1. یک سفارش کم‌مبلغ بسازید.
2. ملت را در Checkout انتخاب کنید.
3. صفحه رسید و انتقال فرم‌محور را مشاهده کنید.
4. مبلغ ریالی صفحه بانک را با سفارش تطبیق دهید.
5. پرداخت را کامل کنید.
6. بازگشت به فروشگاه و صفحه نتیجه را بررسی کنید.
7. Transaction ID را با SaleReferenceId پنل تطبیق دهید.
8. یادداشت موفق Verify و Settle را کنترل کنید.
9. وضعیت سفارش و کاهش موجودی را بررسی کنید.

لغو توسط مشتری

1. سفارش تازه‌ای بسازید.
2. در صفحه بانک پرداخت را لغو کنید.
3. مطمئن شوید سفارش پرداخت‌شده نمی‌شود.
4. امکان تلاش دوباره مشتری را بررسی کنید.

تلاش دوباره برای یک سفارش

1. پرداخت اول را پیش از تکمیل ترک کنید.
2. دوباره همان سفارش را پرداخت کنید.
3. اطمینان یابید درخواست جدید Order ID و RefId تازه می‌گیرد.
4. نتیجه تلاش قدیمی نباید به‌عنوان پرداخت تلاش جدید پذیرفته شود.

Callback تکراری

Callback موفق را دوباره بارگذاری کنید. سفارش نباید دوباره تکمیل، موجودی دوباره کم یا یادداشت مالی تکراری نامناسب ایجاد شود.

Checkout موبایل

پرداخت و بازگشت را در مرورگر موبایل واقعی آزمایش کنید. جابه‌جایی میان مرورگر، اپ بانکی و فروشگاه نباید داده سفارش را از بین ببرد.

بازپرداخت

پس از تأیید تسویه یک سفارش آزمایشی، یک Refund جزئی کم‌مبلغ اجرا کنید. نتیجه ووکامرس، یادداشت سفارش و پنل به‌پرداخت را با هم مقایسه کنید.

چک‌لیست راه‌اندازی

• [ ] قرارداد و پایانه فعال به‌پرداخت دریافت شده است.
• [ ] Terminal ID، نام کاربری و رمز متعلق به یک پایانه هستند.
• [ ] دامنه نهایی فروشگاه برای پایانه ثبت شده است.
• [ ] IP عمومی خروجی واقعی سرور ثبت شده است.
• [ ] HTTPS و گواهی TLS معتبر هستند.
• [ ] اتصال خروجی به bpm.shaparak.ir برقرار است.
• [ ] صفحات پرداخت و Callback از کش مستثنا هستند.
• [ ] Referrer-Policy انتقال فرم را مختل نمی‌کند.
• [ ] واحد پول و تبدیل ریال یا تومان آزمایش شده است.
• [ ] عنوان و توضیحات Checkout تنظیم شده‌اند.
• [ ] تصمیم ارسال موبایل با سیاست حریم خصوصی هماهنگ است.
• [ ] پرداخت موفق و لغوشده آزمایش شده‌اند.
• [ ] Callback تکراری آزمایش شده است.
• [ ] کدهای 43 و 45 به‌درستی مدیریت می‌شوند.
• [ ] سناریوی Verify نامشخص و Settle ناموفق برای تیم پشتیبانی تعریف شده است.
• [ ] روش بررسی on-hold در پنل به‌پرداخت مستند شده است.
• [ ] Refund جزئی کنترل‌شده آزمایش شده است.
• [ ] همه اعتبارنامه‌ها در تصاویر و گزارش‌ها محو شده‌اند.

عیب‌یابی

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

درگاه ملت در Checkout نمایش داده نمی‌شود

• سوییچ درگاه را بررسی کنید؛
• لایسنس Pro را کنترل کنید؛
• Terminal ID را کامل کنید؛
• فعال‌بودن روش در تنظیمات پرداخت ووکامرس را بررسی کنید؛
• Checkout را بدون کش باز کنید؛
• محدودیت مبلغ یا واحد پول را بررسی کنید؛
• خطای JavaScript یا تداخل Checkout را کنترل کنید.

خطای اطلاعات پذیرنده یا کد ۲۴ دریافت می‌شود

• Terminal ID، نام کاربری و رمز را دوباره وارد کنید؛
• مطمئن شوید هر سه مقدار متعلق به یک پایانه‌اند؛
• فاصله یا نویسه پنهان را حذف کنید؛
• از پشتیبانی به‌پرداخت وضعیت فعال اعتبارنامه را بپرسید؛
• پس از تغییر رمز، تنظیمات سایت را بروزرسانی کنید.

خطای IP یا کد ۴۲۱ دیده می‌شود

• IP دامنه را با IP خروجی اشتباه نگیرید؛
• IP خروجی PHP را از هاست دریافت کنید؛
• NAT، Proxy یا تغییر دیتاسنتر را بررسی کنید؛
• IP را برای همان Terminal ID ثبت کنید؛
• پس از تأیید به‌پرداخت، یک درخواست Pay جدید بسازید.

درخواست Pay با خطای تکراری‌بودن متوقف می‌شود

کد 41 نشان می‌دهد شماره درخواست قبلاً استفاده شده است. نسخه بررسی‌شده برای هر تلاش یک شمارنده یکتا می‌سازد. اگر این خطا تکرار می‌شود، مقدار گزینه شمارنده، انتقال ناقص دیتابیس یا اجرای هم‌زمان غیرعادی را بررسی کنید و بدون شناخت ساختار، شمارنده را حذف نکنید.

RefId دریافت می‌شود اما مشتری وارد بانک نمی‌شود

• صفحه رسید را از کش خارج کنید؛
• فرم aio-wc-mellat-form را در HTML بررسی کنید؛
• خطاهای JavaScript را ببینید؛
• دکمه دستی پرداخت را آزمایش کنید؛
• بهینه‌ساز HTML یا Script را موقتاً غیرفعال کنید؛
• منقضی یا خالی‌نبودن RefId سفارش را بررسی کنید.

به‌پرداخت خطای دامنه یا کد ۶۲ می‌دهد

• دامنه ثبت‌شده پذیرنده را با URL نهایی سایت مقایسه کنید؛
• تفاوت www و بدون www را بررسی کنید؛
• Redirect از HTTP به HTTPS را کنترل کنید؛
• Referrer-Policy بسیار محدود مانند no-referrer را بازبینی کنید؛
• انتقال را با فرم خود افزونه انجام دهید و Redirect سفارشی نسازید.

Callback سفارش را پیدا نمی‌کند

• حفظ Query String و wc_order را در Redirectها بررسی کنید؛
• وجود SaleOrderId در داده بازگشتی را کنترل کنید؛
• WAF و افزونه امنیتی را بررسی کنید؛
• Basic Authentication یا حالت تعمیر را از Callback بردارید؛
• Order ID ملت را در متای سفارش و پنل تطبیق دهید.

خطای تطبیق RefId یا SaleOrderId ثبت شده است

این خطا یک کنترل امنیتی است. Verify برای Callback نامنطبق اجرا نمی‌شود.

• سفارش و تلاش پرداخت صحیح را پیدا کنید؛
• چند تب یا تلاش هم‌زمان مشتری را بررسی کنید؛
• از تغییر دستی Callback جلوگیری کنید؛
• RefId را بدون تغییر حروف مقایسه کنید؛
• تراکنش را با SaleReferenceId در پنل بررسی کنید.

پرداخت انجام شده اما Verify پاسخ نداده است

سفارش باید on-hold باشد. کالا یا دسترسی را تحویل ندهید.

• SaleReferenceId را در پنل به‌پرداخت جست‌وجو کنید؛
• زمان Callback را با بازه ۲۰ دقیقه‌ای مقایسه کنید؛
• اتصال SOAP، DNS، TLS و فایروال را بررسی کنید؛
• وضعیت بازگشت خودکار وجه را از پنل یا پشتیبانی پیگیری کنید؛
• تنها پس از سند مالی، وضعیت سفارش را تغییر دهید.

مبلغ Callback با سفارش تفاوت دارد

در این حالت سفارش on-hold می‌شود و Settle یا Reverse اجرا نمی‌شود.

• واحد پول و تبدیل تومان به ریال را بررسی کنید؛
• مالیات، تخفیف، ارسال و افزونه چندارزی را کنترل کنید؛
• مبلغ ذخیره‌شده و FinalAmount را مقایسه کنید؛
• وضعیت تراکنش را فوراً در پنل به‌پرداخت بررسی کنید؛
• تا تعیین تکلیف، سفارش را ارسال نکنید.

Verify موفق است اما Settle ناموفق شده

سفارش برای جلوگیری از تحویل روی on-hold قرار می‌گیرد.

• کد Settle و SaleReferenceId را از یادداشت سفارش بردارید؛
• وضعیت تراکنش را در پنل به‌پرداخت بررسی کنید؛
• در صورت امکان، تسویه را مطابق فرایند پشتیبانی به‌پرداخت انجام دهید؛
• نتیجه واریز را قطعی کنید؛
• سپس سفارش را از on-hold خارج کنید.

Refund با کد ۴۲ یا ۴۶ رد می‌شود

تراکنش ممکن است پیدا نشده یا هنوز تسویه نشده باشد.

• مطمئن شوید سفارش با همین درگاه پرداخت شده است؛
• وجود SaleOrderId و SaleReferenceId را بررسی کنید؛
• نتیجه Settle را در سفارش و پنل کنترل کنید؛
• مبلغ Refund را با مانده قابل‌بازپرداخت مقایسه کنید؛
• محدودیت زمانی یا دسترسی سرویس Refund را از به‌پرداخت بپرسید.

خطای SOAP، DNS یا TLS دیده می‌شود

• دسترسی خروجی پورت ۴۴۳ را بررسی کنید؛
• Resolve شدن bpm.shaparak.ir را از همان سرور آزمایش کنید؛
• بسته CA و تاریخ گواهی‌ها را بروزرسانی کنید؛
• ساعت سیستم را کنترل کنید؛
• از هاست بخواهید اتصال PHP را آزمایش کند؛
• SSL Verification را برای دورزدن خطا غیرفعال نکنید.

نکات امنیتی و عملیاتی

• Terminal ID، نام کاربری و رمز را فقط در اختیار مدیران مجاز قرار دهید؛
• اعتبارنامه را در ویدئو، تصویر، تیکت عمومی یا گزارش قابل دانلود نشان ندهید؛
• RefId را دقیق و بدون تغییر نگه دارید؛
• Callback را بر اساس RefId و SaleOrderId به سفارش متصل کنید؛
• SaleReferenceId یکسان را برای دو سفارش نپذیرید؛
• Verify موفق را بدون Settle موفق، پرداخت کاملاً نهایی‌شده تلقی نکنید؛
• سفارش on-hold را پیش از بررسی پنل ارسال نکنید؛
• شماره کارت فقط باید به‌شکل ماسک‌شده ذخیره یا نمایش داده شود؛
• مسیرهای Checkout و Callback را از کش و محدودیت تعاملی خارج کنید؛
• پس از تغییر هاست، IP، دامنه، رمز یا واحد پول، پرداخت کامل را دوباره آزمایش کنید؛
• نتیجه Refund را از پنل مالی نیز تأیید کنید؛
• برای مغایرت مبلغ یا تسویه ناموفق، روند داخلی مشخصی میان پشتیبانی و امور مالی داشته باشید.

آموزش‌های مرتبط

• تنظیمات مشترک درگاه‌های پرداخت ووکامرس
• راه‌اندازی درگاه پرداخت زرین‌پال ووکامرس
• راه‌اندازی درگاه پرداخت زیبال ووکامرس
• راه‌اندازی درگاه پرداخت سامان SEP ووکامرس
• راه‌اندازی پرداخت اقساطی اسنپ‌پی ووکامرس
• آشنایی با محیط جم پک و مدیریت ماژول‌ها

منابع فنی

• وب‌سایت رسمی به‌پرداخت ملت
• راهنمای فنی به‌پرداخت ملت با عنوان «شرح توابع و متدهای دروازه پرداخت اینترنتی بانک ملت»، نگارش ۱.۲۹؛ مرجع پیاده‌سازی اعلام‌شده در کد نسخه بررسی‌شده
• WooCommerce Payment Gateway API
• WooCommerce Order Refunds API