آماده شبیه‌سازیAPI v3

مستندات کارت اعتباری ایران‌کیش

پروفایل محدود IRANKISH_API_V3 فقط خرید استاندارد Purchase را شبیه‌سازی می‌کند. terminalId، acceptorId، passPhrase و کلید عمومی ساختگی هر اتصال را از داشبورد بگیرید. کلید خصوصی نزد SimLab می‌ماند. RSAES-PKCS1-v1_5 در این پروفایل انتخاب سازگاری SimLab است؛ گواهی پایانه زنده ایران‌کیش نیست.

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

BASE=https://<simlab-host>/api/sandbox/irankish/<connection-id>
TOKEN=$BASE/api/v3/tokenization/make
PAYMENT_POST=$BASE/iuiv3/IPG/Index/
CONFIRM=$BASE/api/v3/confirmation/purchase
INQUIRY=$BASE/api/v3/inquiry/single

توکن و بازگشت

درخواست JSON توکن شامل authenticationEnvelope و request است. متن رمزنگاری، بایت‌های hex حاصل از چسباندن terminalId، passPhrase و مبلغ دوازده‌رقمی ریالی است. آن را با AES-128-CBC/PKCS7 رمز کنید، SHA-256 خروجی را با کلید AES در پاکت RSA قرار دهید و IV را جدا بفرستید. سپس tokenIdentity را با فرم POST به PAYMENT_POST بدهید. صفحه تست اطلاعات کارت نمی‌گیرد و پاسخ را فقط از مرورگر با POST به revertUri می‌فرستد.

تأیید و استعلام

بازگشت مرورگر اثبات پرداخت نیست. پذیرنده باید terminalId، شماره مرجع دوازده‌رقمی، شماره پیگیری شش‌رقمی و tokenIdentity را از سرور خود به CONFIRM بفرستد. تأیید موفق تأیید و تسویه را یکجا نهایی می‌کند. توکن ده دقیقه از ایجاد، تأیید بیست دقیقه از پرداخت و استعلام هفت روز از ایجاد معتبرند. reversePurchase و عملیات کارت واقعی در این پروفایل پشتیبانی نمی‌شوند.

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

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

این نمونه تا ساخت پاکت معتبر قابل ارسال نیست. plaintext برابر hex اتصال terminalId + passPhrase + amount دوازده‌رقمی است. آن را با AES-128-CBC/PKCS7 و کلید/IV تصادفی ۱۶ بایتی رمز کنید؛ SHA-256 متن رمز را به کلید AES بچسبانید و ۴۸ بایت حاصل را با publicKey همین اتصال و RSAES-PKCS1-v1_5 رمز کنید. data نتیجه RSA به hex و iv به hex است؛ private key فقط نزد SimLab می‌ماند. requestTimestamp ثانیه Unix جاری است.

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

POST /api/v3/tokenization/make
Content-Type: application/json

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

{
  "authenticationEnvelope": {
    "data": "<512_HEX_RSA_ENCRYPTED_AES_KEY>",
    "iv": "<32_HEX_IV>"
  },
  "request": {
    "terminalId": "YOUR_terminalId",
    "acceptorId": "YOUR_acceptorId",
    "amount": "250000",
    "requestId": "ORDER9001",
    "requestTimestamp": 1791203083,
    "revertUri": "https://merchant.example.test/payment/callback",
    "transactionType": "Purchase"
  }
}

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

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

شروع صفحه پرداخت: توکن را با فرم POST به /iuiv3/IPG/Index/ ببرید.
بازگشت به سایت: POST مرورگر با token، acceptorId، responseCode، RequestId، amount و در موفقیت retrievalReferenceNumber و systemTraceAuditNumber؛ موقت است.
اطلاعاتی که باید نگه دارید: requestId، amount، tokenIdentity، RRN و trace را نگه دارید و تطبیق دهید.
معیار نهایی موفقیت: POST /api/v3/confirmation/purchase؛ فقط Confirm موفق نهایی است. Inquiry فقط وضعیت فعلی را می‌خواند.
درخواست تکراری: requestId یکسان با اثرانگشت یکسان بازپخش؛ تفاوت درخواست تعارض است.
مهلت‌ها: Token ده دقیقه و Confirm بیست دقیقه پس از پرداخت؛ Inquiry تا هفت روز.
عملیات قابل استفاده: دریافت شناسه، پرداخت، تأیید و استعلام
خارج از محدوده: برگشت توسط پذیرنده، بازپرداخت و کارت واقعی

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

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

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

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

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

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

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

مرز ایمنی

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

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