آماده شبیه‌سازیVPG REST

مستندات پرداخت الکترونیک سداد

نسخه محدود SADAD_VPG_REST_V0 از REST و امضای 3DES استفاده می‌کند. TerminalId، MerchantId و Key ساختگی را از اتصال فعال خود بگیرید. Amount یک عدد صحیح مثبت به ریال است.

مسیرها

BASE=https://<simlab-host>/api/sandbox/sadad/<connection-id>
CREATE=$BASE/api/v0/Request/PaymentRequest
PURCHASE=$BASE/Purchase?Token=<returned-token>
VERIFY=$BASE/api/v0/Advice/Verify

نام‌های مستعار VPG/... و vpg/... برای هر سه مسیر پشتیبانی می‌شوند. مسیرهای خارج از این مجموعه و محصولات ویژه سداد اجرا نمی‌شوند.

امضا

Key دقیقاً 24 بایت Base64 است. برای ایجاد، رشته UTF-8 TerminalId;OrderId;Amount را با 3-key Triple DES EDE، حالت ECB و padding هشت‌بایتی PKCS رمز کرده و خروجی را Base64 کنید. برای تأیید، همان الگوریتم را روی متن دقیق توکن اعمال کنید. هرگز Key یا SignData را لاگ نکنید.

import { createCipheriv } from 'node:crypto';
function sign(text: string, keyBase64: string) {
  const key = Buffer.from(keyBase64, 'base64');
  if (key.length !== 24) throw new Error('Invalid test key');
  const cipher = createCipheriv('des-ede3', key, null);
  return Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]).toString('base64');
}


const signData = sign(terminalId + ';' + orderId + ';' + amount, keyBase64);

$key = base64_decode($keyBase64, true);
if ($key === false || strlen($key) !== 24) throw new RuntimeException('Invalid test key');
$plain = $terminalId . ';' . $orderId . ';' . $amount;
$raw = openssl_encrypt($plain, 'des-ede3', $key, OPENSSL_RAW_DATA);
if ($raw === false) throw new RuntimeException('Signing failed');
$signData = base64_encode($raw);

var key = java.util.Base64.getDecoder().decode(keyBase64);
if (key.length != 24) throw new IllegalArgumentException("Invalid test key");
var cipher = javax.crypto.Cipher.getInstance("DESede/ECB/PKCS5Padding");
cipher.init(javax.crypto.Cipher.ENCRYPT_MODE,
  new javax.crypto.spec.SecretKeySpec(key, "DESede"));
var plain = terminalId + ";" + orderId + ";" + amount;
var signData = java.util.Base64.getEncoder().encodeToString(
  cipher.doFinal(plain.getBytes(java.nio.charset.StandardCharsets.UTF_8)));

۱. ایجاد و صفحه پرداخت

درخواست JSON یا form-urlencoded بفرستید. رشته‌های OrderId و Amount از تبدیل عددی با افت دقت جلوگیری می‌کنند. پاسخ موفق JSON شامل ResCode="0" و Token است. سپس مرورگر را با GET به PURCHASE ببرید؛ فقط یک پارامتر Token یا token مجاز است.

curl --fail-with-body -H 'Content-Type: application/json' \
  --data '{"MerchantId":"YOUR_MERCHANT_ID","TerminalId":"YOUR_TERMINAL_ID","Amount":"250000","OrderId":"1001","LocalDateTime":"2026-09-25 12:00:00","ReturnUrl":"https://merchant.example.test/sadad/callback","SignData":"CALCULATED_BASE64"}' \
  "$CREATE"

const response = await fetch(createUrl, {
  method: 'POST', headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ MerchantId: merchantId, TerminalId: terminalId,
    Amount: amount, OrderId: orderId, LocalDateTime: localDateTime,
    ReturnUrl: returnUrl, SignData: signData })
});
const result = await response.json();
if (response.status !== 200 || result.ResCode !== '0') throw new Error(result.ResCode);
const purchaseUrl = baseUrl + '/Purchase?Token=' + encodeURIComponent(result.Token);

۲. بازگشت مرورگر

صفحه تست چهار نتیجه موفق، انصراف، خطا و پایان مهلت دارد؛ ورودی کارت ندارد. فرم POST مرورگر شش فیلد ResCode، Description، PrimaryAccNo، token، hashedCardNo و OrderId را می‌فرستد. دو فیلد کارت فقط مقادیر مصنوعی‌اند. token با حرف کوچک است. پایان مهلت فرم موفق تولید نمی‌کند و آماده شدن فرم اثبات تحویل نیست.

۳. تأیید

سمت سرور از روی توکن دقیق بازگشت، امضای جدید بسازید و {"Token":"...","SignData":"..."} را به تأیید POST کنید. MerchantId/TerminalId در بدنه تأیید وجود ندارد. نخستین تأیید موفق ResCode="0" و تأیید موفق تکراری "100" برمی‌گرداند؛ هر دو مرجع پایدار RetrivalRefNo و SystemTraceNo دارند. املای RetrivalRefNo عمدی است. سداد در این نسخه تسویه، برگشت یا استعلام ندارد.

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

• 1005 همراه HTTP 403: دسترسی SimLab مجاز نیست.
• 1012: MerchantId/TerminalId نامعتبر.
• 1025: امضای CREATE نامعتبر؛ امضای تأیید نامعتبر -1 است.
• 1011: OrderId تکراری با درخواست متفاوت.
• 1101 و 1026: مبلغ یا شناسه سفارش نامعتبر.
• 1072 همراه HTTP 422: فیلد محصول ویژه یا سناریوی پشتیبانی‌نشده.

درخواست JSON/form بیش از 64 KiB پذیرفته نمی‌شود. بازگشت را با سفارش و مبلغ ذخیره‌شده خود تطبیق دهید و فقط پس از تأیید موفق، سفارش را تکمیل کنید.

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

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

ابتدا SignData را با Key ساختگی همین اتصال و الگوریتم TripleDES EDE/ECB قرارداد بر اساس TerminalId;OrderId;Amount بسازید؛ مقدار داخل نمونه جای‌نگهدار است و قبل از امضا قابل ارسال نیست.

POST /api/v0/Request/PaymentRequest
Content-Type: application/json

{
  "MerchantId": "YOUR_MerchantId",
  "TerminalId": "YOUR_TerminalId",
  "Amount": "250000",
  "OrderId": "9001",
  "LocalDateTime": "2026/09/27 12:00:00",
  "ReturnUrl": "https://merchant.example.test/payment/callback",
  "SignData": "<BASE64_3DES_PROOF>"
}

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

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

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

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

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

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

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

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

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

مرز ایمنی

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