به راهنمای سرویس اتصال به درگاه پرداخت اینترنتی ایران درگاه
خوش آمدید. این مستندات، جهت راهنمایی شما در استفاده از وب
سرویس ایران درگاه تهیه شده است. در صورت وجود هرگونه سوال یا
اشکال در هر مرحله می‌توانید با ما تماس بگیرید. لطفا قبل از
پیاده‌سازی به نکات زیر توجه نمایید:
درخواست‌ها به صورت
REST و
SOAP می‌باشند؛با
انتخاب هر یک از حالت‌ها در بالای همین صفحه می‌توانید توضیحات
مربوط به آن روش را مشاهده نمایید.
در صورت دریافت هرگونه خطا، ابتدا پارامترهای ارسالی خود را
بررسی نمایید. پس از بررسی، در صورتی که همچنان خطا رفع نشده
باشد، پارامترهای ارسالی را به همراه تصویر خطا برای ما ارسال
کنید تا در اسرع وقت توسط تیم فنی بررسی و مشکل شما رفع شود.
جهت انجام تست حتما از محیط سندباکس استفاده
نمایید که توضیحات مربوط به این محیط در هر مرحله داده شده
است.
راهنمای کلی
جهت اتصال به درگاه پرداخت، تنها کافیست چهار مرحله زیر را پس از
دریافت کد مرچنت پیاده کنید:
ایجاد تراکنش: در این مرحله، اطلاعات تراکنش
خود را برای ما ارسال کنید تا در پاسخ به شما، شناسه تراکنش
(authority) بازگردانده شود. شناسه تراکنش را حتما در نزد خود
نگه دارید (می‌توانید آن را در پایگاه داده خود ذخیره نمایید)
تا در ادامه مراحل با مشکل مواجه نشوید.
هدایت کاربر به درگاه:با استفاده از شناسه
تراکنش دریافت‌شده، کاربر را به آدرس مشخص شده هدایت کنید تا
کاربر شما به درگاه رفته و عملیات پرداخت را انجام دهد.
بازگشت اطلاعات:در این مرحله، کاربر پس از
انجام تراکنش یا انصراف از تراکنش به صفحه فروشگاه هدایت
خواهد‌شد که اطلاعات تراکنش به صورت POST به آدرس callback که
در مرحله اول ارسال کرده‌اید، ارسال خواهد‌شد.
تایید تراکنش: در این مرحله، اطلاعات تراکنش
که قبلا به آدرس callbackURL ارسال شده‌بود، بازگردانده
می‌شود. در صورتی که تراکنش موفقیت‌آمیز بوده باشد، برای تایید
تراکنش، حتما باید متد تایید تراکنش را فراخوانی کنید تا کد
پیگیری تراکنش برای شما ارسال گردد.
با استفاده از ارسال اطلاعات به صورت POST، به آدرس درخواست،
تراکنش را ایجاد و اطلاعات جدول زیر را ارسال نمایید :
نام فیلد
نوع
ضروری
توضیحات
merchantID
String
اجباری
مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه
بانکی(مقدار این پارامتر برای محیط تست برابر با TEST می‌باشد.)
amount
Integer
اجباری
مبلغ تراکنش به ریال بدون اعشار و بزرگتر یا مساوی 10,000
callbackURL
String
اجباری
آدرس بازگشتی که باید به صورت urlencode ارسال شود و باید با
آدرس درگاه پرداخت تایید شده در هنگام دریافت درگاه در ﯾﮏ
آدرس ﺑﺎﺷﺪ.
orderId
String
اجباری
شماره سفارش شما
cardNumber
String
اختیاری
شماره کارت پرداخت‌کننده است که این شماره کارت بعد از انجام
عملیات پرداخت با شماره کارت دریافتی از بانک تطابق داده
می‌شود و درصورتی که یکسان نباشد، مبلغ تراکنش به حساب
پرداخت‌کننده برمی‌گردد.
(مقدار این پارامتر برای محیط تست برابر با 1234123412341234 می‌باشد.)
mobile
String
اختیاری
شماره همراه پرداخت کننده تراکنش
description
String
اختیاری
توضیحات تراکنش
در پاسخ به فراخوانی متد، مقادیر زیر برگردانده خواهد‌شد :
status: کد خطای وضعیت تراکنش است که در صورتی
که برابر با ۲۰۰ باشد، تراکنش موفقیت‌آمیز بوده است؛ درغیر این
صورت تراکنش دارای خطا است.
authority: در صورت موفقیت‌آمیز بودن اتصال،
شناسه یکتا جهت اتصال به درگاه ایران درگاه، در این پارامتر قرار
دارد؛ در غیر این صورت تراکنش دارای خطا است.
message: پیام وضعیت تراکنش در این پارامتر
قرار دارد.
2- هدایت کاربر به درگاه
در صورتی که پاسخ ایجاد تراکنش موفقیت‌آمیز باشد، می‌توانید با
استفاده از شناسه تراکنش، کاربر را به درگاه هدایت نمایید.
نکته: در این مرحله، تنها تا 4 دقیقه پس از ایجاد
تراکنش، امکان هدایت کاربر به درگاه وجود دارد و در غیر این صورت،
کاربر خطا دریافت می کند.
3- بازگشت اطلاعات
در این مرحله، کاربر پس از انجام تراکنش یا انصراف از تراکنش به
صفحه فروشگاه هدایت خواهد‌شد که اطلاعات تراکنش به صورت POST به
آدرس callback که در مرحله اول ارسال کرده‌اید، ارسال خواهد‌شد.
داده‌های دریافتی به شرح زیر می‌باشد:
نام فیلد
نوع
توضیحات
code
Int
کد وضعیت پرداخت تراکنش می‌باشد، مقدار 100 برابر با پرداخت
موفقیت‌آمیز می‌باشد.
message
String
پیام مربوط به وضعیت تراکنش
authority
String
شناسه مربوط به تراکنش
amount
Int
مبلغ تراکنش
orderId
String
شماره سفارش ارسالی در مرحله اول
4- تایید تراکنش
پس از انجام این مرحله، عملیات پرداخت، در پنل فروشگاه تایید خواهد
شد. لازم به ذکر است، انجام این مرحله، برای تایید شدن عملیات
پرداخت، الزامی می‌باشد.
درصورتی که کاربر تراکنش را با موفقیت انجام داده‌باشد و کد "100"
در مرحله قبل دریافت‌شده باشد اطلاعات جدول زیر را در متد
IRDVerification باید ارسال شود.
درصورتی که کاربر، تراکنش را با موفقیت انجام داده‌باشد و کد "100"
در مرحله قبل دریافت‌شده باشد، باید اطلاعات جدول زیر، در آدرس
بالا ارسال شود.
نام فیلد
نوع
توضیحات
merchantID
String
مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه بانکی
(مقدار این پارامتر برای محیط تست برابر با TEST می‌باشد.)
authority
String
شناسه تراکنش
amount
Integer
مبلغ تراکنش به ریال، بدون اعشار و بزرگتر یا مساوی 10,000
orderId
String
شماره سفارش شما
در نهایت داده‌های دریافتی به شرح زیر می‌باشد:
نام فیلد
نوع
توضیحات
status
Integer
وضعیت تایید تراکنش. مقدار "100" برابر با تاییدیه موفق
می‌باشد
message
String
پیام مربوط به وضعیت تایید تراکنش
refId
String
شماره پیگیری تراکنش
orderId
String
شماره سفارش شما
cardNumber
String
شماره کارت پرداخت کننده تراکنش
نشان اعتماد ایران درگاه :
با توجه به لزوم جلب اعتماد مشتریان جهت انجام پرداختی امن و سریع،
می‌توانید با قراردادن کد زیر در قسمتی از وبسایت خود، که برای
کاربران قابل مشاهده باشد (مانند فوتر وبسایت)، مشتریان خود را از
پردازش پرداخت توسط ایران درگاه، مطمئن سازید.
