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

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

پروفایل محدود SEP_ONLINEPG_REST قرارداد OnlinePG را شبیه‌سازی می‌کند. از اتصال فعال خود TerminalId و کلید ساختگیSimLabKey بگیرید. کلید را فقط در سرور نگه دارید؛ هدرX-SimLab-Key حفاظ مخصوص SimLab است و در درگاه واقعی سامان وجود ندارد.

امضا و حفاظ آزمایشی

این پروفایل امضای رمزنگاری درون پیام ندارد. قرارداد انتخاب‌شده سامان بر دسترسی سرور پذیرنده از IP ثبت‌شده تکیه دارد؛ SimLab به‌جای اعتماد به شناسه پایانه، X-SimLab-Key را برای ایجاد، تأیید و برگشت الزامی می‌کند. این هدر در فرم پرداخت و بازگشت مرورگر ارسال نمی‌شود و جزئی از API واقعی سامان نیست. TxnRandomSessionKey اختیاری در این نسخه پشتیبانی نمی‌شود.

مسیرهای دقیق

مسیرهای اتصال

BASE=https://<simlab-host>/api/sandbox/sep/<connection-id>
CREATE=$BASE/onlinepg/onlinepg
PAYMENT_POST=$BASE/OnlinePG/OnlinePG
VERIFY=$BASE/verifyTxnRandomSessionkey/ipg/VerifyTransaction
REVERSE=$BASE/verifyTxnRandomSessionkey/ipg/ReverseTransaction

۱. توکن پرداخت

درخواست JSON را از سرور پذیرنده با هدر X-SimLab-Key بفرستید. مبلغ ریال صحیح مثبت است و برای مقدار بزرگ‌تر از حداکثر عدد امن JavaScript باید رشته ده‌دهی باشد. پاسخ موفق status: 1 وtoken برمی‌گرداند. ResNum برای همین اتصال شناسه یکتای سفارش است.

بدنه JSON ایجاد توکن

{"Action":"Token","TerminalId":"12345678","Amount":12000,"ResNum":"ORDER-1001","RedirectUrl":"https://merchant.example/callback"}

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

مرورگر فرم POST با تنها فیلد Token به مسیر PAYMENT_POST می‌فرستد. توکن برای شروع پرداخت ۲۰ دقیقه معتبر است. صفحه تست هیچ فیلد کارتی ندارد. مرورگر سپس فرم بازگشت را به RedirectUrl می‌فرستد؛ سرور SimLab بازگشت را مستقیم تحویل نمی‌دهد. فیلدهای اصلی بازگشتResNum، RefNum، State،Status، Amount و شناسه پایانه‌اند. بازگشت به تنهایی اثبات پرداخت نیست.

۳. تأیید و برگشت

از سرور خود JSON شامل RefNum بازگشت وTerminalNumber اتصال را با همان هدر کلید به تأیید بفرستید.ResultCode: 0 تأیید موفق و 2 بازپخش همان تأیید است. تأیید تازه تا ۳۰ دقیقه پس از پرداخت شبیه‌سازی‌شده ممکن است. برگشت فقط پس از تأیید موفق و تا ۵۰ دقیقه پس از پرداخت اجرا می‌شود. برگشت به‌عنوان رخداد جداگانه ثبت می‌شود؛ نتیجه تاریخی پرداخت بازنویسی نمی‌شود.

بدنه JSON تأیید و برگشت

{"RefNum":"<returned-reference>","TerminalNumber":"12345678"}

کدهای نتیجه و تطبیق مبلغ

در پاسخ تأیید، علاوه بر ResultCode، مرجع و TerminalNumber و TransactionDetail.OrginalAmount را با سفارش ذخیره‌شده تطبیق دهید. املای OrginalAmount مطابق قرارداد است. status:1 در ایجاد، Status:2 در بازگشت و ResultCode:0 در تأیید سه مفهوم متفاوت‌اند؛ یکی را جای دیگری نخوانید.

مرجع ناشناخته -2، مهلت سپری‌شده -6 و رسید برگشت‌خورده در تأیید کد 5 دارد. درخواست با اعتبارنامه نادرست یا اشتراک منقضی با HTTP 403 رد می‌شود. این پروفایل استعلام، تسویه مستقل، بازپرداخت، محصولات جانبی و سازگاری همه پایانه‌های واقعی سامان را ارائه نمی‌کند.

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

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

X-SimLab-Key فقط اثبات آزمایشی SimLab برای درخواست سروری است؛ آن را به مرورگر نفرستید.

روش، مسیر و هدرهای درخواست

POST /onlinepg/onlinepg
Content-Type: application/json
X-SimLab-Key: YOUR_SimLabKey

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

{
  "Action": "Token",
  "TerminalId": "YOUR_TerminalId",
  "Amount": "250000",
  "ResNum": "ORDER-9001",
  "RedirectUrl": "https://merchant.example.test/payment/callback"
}

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

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

شروع صفحه پرداخت: Token پاسخ را با فرم POST به /OnlinePG/OnlinePG بفرستید.
بازگشت به سایت: POST مرورگر با Token، ResNum، RefNum، State، Status، TerminalId، MID، RRN، TraceNo و Amount؛ راهنمای موقت است.
اطلاعاتی که باید نگه دارید: ResNum، مبلغ، Token و RefNum را نگه دارید؛ شناسه و مبلغ را پیش از Verify تطبیق دهید.
معیار نهایی موفقیت: VerifyTransaction با RefNum و TerminalNumber؛ فقط پاسخ Verify موفق نهایی است.
درخواست تکراری: ResNum یکسان با اثرانگشت یکسان همان خرید را برمی‌گرداند؛ داده متفاوت رد می‌شود. Reverse مجاز وضعیت جاری را تغییر می‌دهد.
مهلت‌ها: Token بیست دقیقه؛ Verify سی دقیقه و Reverse پنجاه دقیقه پس از پرداخت.
عملیات قابل استفاده: دریافت شناسه، پرداخت، تأیید و برگشت پس از تأیید
خارج از محدوده: استعلام، تسویه مستقل، بازپرداخت و کارت واقعی

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

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

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

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

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

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

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

مرز ایمنی

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

نمای عمومی درگاه