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