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

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

ResCode در چه مرحله‌ای استفاده می‌شود؟

فرایند پرداخت آنلاین معمولاً از چند مرحله تشکیل می‌شود. ابتدا سایت درخواست پرداخت را به سرویس بانک ارسال می‌کند. اگر درخواست اولیه درست باشد، بانک یک شناسه پرداخت مثل RefId برمی‌گرداند و کاربر به صفحه پرداخت هدایت می‌شود. بعد از پرداخت، بانک کاربر را به آدرس برگشت سایت بازمی‌گرداند و پارامترهایی مثل ResCode، SaleOrderId و SaleReferenceId ارسال می‌شود.

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

چرا Verify و کنترل مبلغ ضروری است؟

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

• برای هر سفارش یک شناسه پرداخت یکتا ایجاد کنید.
• اگر سفارش قبلاً پرداخت شده، عملیات را دوباره انجام ندهید.
• مبلغ برگشتی و مبلغ ذخیره‌شده در دیتابیس را تطبیق دهید.
• نتیجه Verify و Settle را در جدول تراکنش‌ها ذخیره کنید.
• در صورت خطای نامشخص، سفارش را در وضعیت «در حال بررسی» قرار دهید، نه پرداخت‌شده.

نمونه ساده بررسی وضعیت در PHP

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

<?php
$resCode = $_POST["ResCode"] ?? null;
$saleOrderId = $_POST["SaleOrderId"] ?? null;
$saleReferenceId = $_POST["SaleReferenceId"] ?? null;

if ($resCode !== "0") {
    // پرداخت ناموفق یا انصراف کاربر
    markOrderAsUnpaid($saleOrderId, $resCode);
    exit("پرداخت با موفقیت انجام نشد.");
}

// 1) سفارش را از دیتابیس بخوانید
$order = findOrderByPaymentId($saleOrderId);

// 2) از پردازش چندباره جلوگیری کنید
if ($order && $order["status"] === "paid") {
    exit("این سفارش قبلاً پرداخت شده است.");
}

// 3) تراکنش را از سمت سرور Verify کنید
$verifyResult = verifyMellatTransaction($saleOrderId, $saleReferenceId);

if ($verifyResult === "0") {
    markOrderAsPaid($saleOrderId, $saleReferenceId);
    exit("پرداخت با موفقیت تایید شد.");
}

markOrderAsPendingReview($saleOrderId, $verifyResult);
exit("وضعیت پرداخت نیاز به بررسی دارد.");

چک‌لیست رفع خطاهای رایج

سوالات متداول درباره کدهای بانک ملت