آماده شبیه‌سازیBPM SOAP

مستندات به‌پرداخت ملت

نسخه اجرایی MELLAT_BPM_SOAP از SOAP 1.1 استفاده می‌کند. اتصال فعال و اعتبارنامه ساختگی terminalId، userName و userPassword را از داشبورد همان کاربر بگیرید. مبلغ ریال مثبت است.

اعتبارنامه و امضا

در این پروفایل امضای جداگانه درخواست وجود ندارد؛ terminalId، userName و userPassword در بدنه SOAP ارسال می‌شوند. از اعتبارنامه ساختگی همان اتصال استفاده کنید و XML را با کتابخانه امن بسازید تا نویسه‌های ویژه رمز یا نشانی بازگشت، ساختار پیام را خراب نکنند. WSDL عمومی اعتبارنامه شما را شامل نمی‌شود.

مسیرها و WSDL

SERVICE=https://<simlab-host>/api/sandbox/mellat/<connection-id>/pgw
WSDL=$SERVICE?wsdl
INTERFACE_WSDL=$SERVICE?wsdl=IPaymentGateway.wsdl
HANDOFF=https://<simlab-host>/api/sandbox/mellat/<connection-id>/startpay.mellat

۱. درخواست ایجاد

XML زیر را با مقدارهای ساختگی خود ذخیره کنید. ترتیب و حروف فیلدها مهم‌اند. مقدار برگشتی bpPayRequestResponse در موفقیت 0,<RefId> است.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:int="http://interfaces.core.sw.bps.com/">
  <soapenv:Body><int:bpPayRequest>
    <terminalId>YOUR_TERMINAL_ID</terminalId>
    <userName>YOUR_USER_NAME</userName>
    <userPassword>YOUR_USER_PASSWORD</userPassword>
    <orderId>9001</orderId><amount>250000</amount>
    <localDate>20260925</localDate><localTime>120000</localTime>
    <additionalData></additionalData>
    <callBackUrl>https://merchant.example.test/mellat/callback</callBackUrl>
    <payerId>0</payerId>
  </int:bpPayRequest></soapenv:Body>
</soapenv:Envelope>

curl --fail-with-body -H 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @mellat-create.xml "$SERVICE"

نمونه ارسال با چهار زبان

همه نمونه‌ها همان XML را می‌فرستند؛ XML را از ورودی کاربر به‌صورت رشته نسازید. مقادیر محرمانه را در فایل عمومی قرار ندهید.

import { readFile } from 'node:fs/promises';
const xml = await readFile('mellat-create.xml', 'utf8');
const response = await fetch(process.env.MELLAT_SERVICE!, {
  method: 'POST', headers: { 'content-type': 'text/xml; charset=utf-8' }, body: xml
});
if (!response.ok) throw new Error('Mellat transport failed: ' + response.status);
const soapResponse = await response.text(); // Parse the SOAP result; never use regex for XML.

$xml = file_get_contents('mellat-create.xml');
$ch = curl_init(getenv('MELLAT_SERVICE'));
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $xml,
  CURLOPT_HTTPHEADER => ['Content-Type: text/xml; charset=utf-8'],
  CURLOPT_RETURNTRANSFER => true]);
$body = curl_exec($ch);
if ($body === false || curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
  throw new RuntimeException('Mellat transport failed');
}
curl_close($ch);
// Parse $body with an XML parser with external entities disabled.

var client = java.net.http.HttpClient.newHttpClient();
var xml = java.nio.file.Files.readString(java.nio.file.Path.of("mellat-create.xml"));
var request = java.net.http.HttpRequest.newBuilder(
  java.net.URI.create(System.getenv("MELLAT_SERVICE")))
  .header("Content-Type", "text/xml; charset=utf-8")
  .POST(java.net.http.HttpRequest.BodyPublishers.ofString(xml)).build();
var response = client.send(request,
  java.net.http.HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) throw new RuntimeException("Mellat transport failed");
// Parse response.body() with a hardened XML parser.

۲. صفحه پرداخت و بازگشت

پس از دریافت RefId، مرورگر را با فرم POST شامل فقط RefId به HANDOFF ببرید. صفحه تست ورودی کارت ندارد. نتیجه موفق، انصراف، خطا یا پایان مهلت در همان صفحه انتخاب می‌شود. فرم بازگشت توسط مرورگر با فیلدهای ResCode، RefId، SaleOrderId و SaleReferenceId به نشانی ثبت‌شده می‌رود. آماده شدن فرم، تحویل قطعی آن نیست. SaleOrderId در این نسخه با حرف بزرگ آغاز می‌شود.

۳. تأیید، استعلام، تسویه و برگشت

بعد از بازگشت موفق، bpVerifyRequest را از سرور خود فراخوانی کنید؛ نتیجه 0 یعنی تأیید موفق. سپس bpSettleRequest را جداگانه اجرا کنید؛ صرف تأیید، تسویه نیست. bpInquiryRequest وضعیت فعلی را می‌خواند. پیش از تسویه، bpReversalRequest می‌تواند پرداخت موفق را برگرداند؛ بعد از تسویه برگشت مجاز نیست.

برای هر عملیات از همان اعتبارنامه، saleOrderId ایجاد اولیه، saleReferenceId بازگشت موفق و یک orderId مستقل برای درخواست فعلی استفاده کنید. ساختار همه عملیات در WSDL منتشرشده است. تکرار دقیق هر عملیات پس از بررسی دسترسی، همان نتیجه ثبت‌شده را می‌دهد؛ تغییر محتوا با شناسه تکراری رد می‌شود.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:int="http://interfaces.core.sw.bps.com/">
  <soapenv:Body><int:bpVerifyRequest>
    <terminalId>YOUR_TERMINAL_ID</terminalId>
    <userName>YOUR_USER_NAME</userName>
    <userPassword>YOUR_USER_PASSWORD</userPassword>
    <orderId>9101</orderId><saleOrderId>9001</saleOrderId>
    <saleReferenceId>RETURNED_SALE_REFERENCE_ID</saleReferenceId>
  </int:bpVerifyRequest></soapenv:Body>
</soapenv:Envelope>

نتیجه‌های مهم

• 21: دسترسی/اعتبارنامه/آمادگی یا اشتراک مجاز نیست.
• 41: تکرار شناسه با محتوای متفاوت.
• 42: سفارش یا مرجع نامنطبق.
• 43: درخواست تأیید تازه برای فروش قبلاً تأییدشده؛ فقط استعلامِ مبتنی بر تأیید ثبت‌شده می‌تواند وضعیت موفق را نشان دهد.
• 44: هنوز تأیید موفق ثبت نشده است.
• 45: تسویه نهایی؛ برگشت بعدی مجاز نیست.
• 48: برگشت قبلاً انجام شده است.

پایان مهلت ممکن است HTTP 504 بدهد؛ آن را موفقیت تلقی نکنید. بدنه SOAP بیش از 64 KiB و فرم بیش از 4 KiB پذیرفته نمی‌شود.

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

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

POST /pgw
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:int="http://interfaces.core.sw.bps.com/"><soapenv:Body><int:bpPayRequest><terminalId>YOUR_terminalId</terminalId><userName>YOUR_userName</userName><userPassword>YOUR_userPassword</userPassword><orderId>9001</orderId><amount>250000</amount><localDate></localDate><localTime></localTime><additionalData></additionalData><callBackUrl>https://merchant.example.test/payment/callback</callBackUrl><payerId>0</payerId></int:bpPayRequest></soapenv:Body></soapenv:Envelope>

چک‌لیست اتصال و نهایی‌سازی

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

خطا در کدام مرحله رخ داده است؟

• پیش از دریافت توکن: مسیر، نوع بدنه، مبلغ و واحد پول، اعتبارنامه و امضای درخواست را بررسی کنید. پاسخ HTTP موفق به‌تنهایی کافی نیست؛ کد نتیجه داخل بدنه نیز باید مطابق قرارداد موفق باشد.
• هنگام ورود به صفحه پرداخت: توکن همان اتصال، روش GET یا POST و اعتبار زمانی آن را بررسی کنید. کلید سروری را در فرم مرورگر یا نشانی صفحه قرار ندهید.
• هنگام بازگشت: نشانی ثبت‌شده، روش فرم یا پارامترهای نشانی و تطابق شناسه سفارش را بررسی کنید. ایجاد فرم بازگشت به معنی دریافت آن توسط سایت شما نیست؛ مرورگر ممکن است بسته شود.
• هنگام تأیید: مرجع، مبلغ و پایانه را از سفارش ذخیره‌شده بخوانید و با پاسخ تطبیق دهید. ورودی بازگشت مرورگر قابل دست‌کاری است. خطای شبکه یا پایان مهلت را به پرداخت موفق تبدیل نکنید.
• پس از تأیید: اگر این پروفایل تسویه یا تأیید نهایی جدا دارد، آن را اجرا کنید. تکرار درخواست را طبق قواعد همین درگاه انجام دهید؛ برای همه درگاه‌ها قاعده تکرار یکسان وجود ندارد.

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

سناریوهای آزمایش و دسترسی

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

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

باز کردن اتصال و بخش آزمایش این درگاه · تاریخچه درخواست‌ها و تراکنش‌ها · راهنمای اولین اتصال

مرز ایمنی

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