مقدمات و پیش‌نیاز‌ها

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

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

راهنمای ‌کلی

جهت اتصال به درگاه پرداخت، تنها کافیست سه مرحله زیر را پس از دریافت کد مرچنت پیاده کنید:

  1. ایجاد تراکنش: در این مرحله، اطلاعات تراکنش خود را برای ما ارسال ‌کنید تا در پاسخ به شما، شناسه تراکنش (authority) بازگردانده شود. شناسه تراکنش را حتما در نزد خود نگه دارید (می توانید آن را در پایگاه داده خود ذخیره نمایید) تا در ادامه مراحل با مشکل مواجه نشوید.
  2. هدایت کاربر به درگاه:با استفاده از شناسه تراکنش دریافت‌شده، کاربر را به آدرس مشخص شده هدایت کنید تا کاربر شما به درگاه رفته و عملیات پرداخت را انجام دهد.
  3. بازگشت اطلاعات:در این مرحله، کاربر پس از انجام تراکنش یا انصراف از تراکنش به صفحه فروشگاه هدایت خواهد‌شد که اطلاعات تراکنش به صورت POST به آدرس callback که در مرحله اول ارسال کرده‌اید، ارسال خواهد‌شد.
  4. تایید تراکنش: در این مرحله، اطلاعات تراکنش که قبلا به آدرس callbackURL ارسال شده‌بود، بازگردانده می‌شود. در صورتی که تراکنش موفقیت‌آمیز بوده باشد، برای تایید تراکنش، حتما باید متد تایید تراکنش را فراخوانی کنید تا کد پیگیری تراکنش برای شما ارسال گردد.

1- ایجاد تراکنش

با استفاده از آدرس بالا فایل WSDL را لود نموده و کلاینت را ایجاد نمایید:

آدرس درخواست:

https://dargaah.com/payment

با استفاده از متد IRDPayment تراکنش را ایحاد نمایید و اطلاعات جدول زیر را ارسال نمایید:

آدرس درخواست به محیط SANDBOX:

https://dargaah.com/sandbox/payment

با استفاده از ارسال اطلاعات به صورت POST، به آدرس درخواست، تراکنش را ایجاد و اطلاعات جدول زیر را ارسال نمایید :

نام فیلد نوع ضروری توضیحات
merchantID String اجباری مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه بانکی (مقدار این پارامتر برای محیط تست برابر با TEST می باشد.)
amount Integer اجباری مبلغ تراکنش به ریال بدون اعشار و بزرگتر یا مساوی 10,000
callbackURL String اجباری آدرس بازگشتی که باید به صورت urlencode ارسال شود و باید با آدرس درگاه پرداخت تایید شده در هنگام دریافت درگاه در ﯾﮏ آدرس ﺑﺎﺷﺪ.
orderId String اجباری شماره سفارش شما
cardNumber String اختیاری شماره کارت پرداخت‌کننده است که این شماره کارت بعد از انجام عملیات پرداخت با شماره کارت دریافتی از بانک تطابق داده می‌شود و درصورتی که یکسان نباشد، مبلغ تراکنش به حساب پرداخت‌کننده برمی‌گردد.
mobile String اختیاری شماره همراه پرداخت کننده تراکنش
description String اختیاری توضیحات تراکنش

در پاسخ به فراخوانی متد، مقادیر زیر برگردانده خواهد‌شد :

status: کد خطای وضعیت تراکنش است که در صورتی که برابر با ۲۰۰ باشد، تراکنش موفقیت‌آمیز بوده است؛ درغیر این صورت تراکنش دارای خطا است.

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

message: پیام وضعیت تراکنش در این پارامتر قرار دارد.

2- هدایت کاربر به درگاه

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

آدرس هدایت به درگاه:

/https://dargaah.com/ird/startpay

آدرس هدایت به محیط SANDBOX:

/https://dargaah.com/sandbox/ird/startpay

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

3- بازگشت اطلاعات

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

داده‌های دریافتی به شرح زیر می‌باشد:

نام فیلد نوع توضیحات
code Int کد وضعیت پرداخت تراکنش می‌باشد، مقدار 100 برابر با پرداخت موفقیت‌آمیز می‌باشد.
message String پیام مربوط به وضعیت تراکنش
authority String شناسه مربوط به تراکنش
amount Int مبلغ تراکنش
orderId String شماره سفارش ارسالی در مرحله اول

4- تایید تراکنش

پس از انجام این مرحله، عملیات پرداخت، در پنل فروشگاه تایید خواهد شد. لازم به ذکر است، انجام این مرحله، برای تایید شدن عملیات پرداخت، الزامی می‌باشد.

درصورتی که کاربر تراکنش را با موفقیت انجام داده‌باشد و کد "100" در مرحله قبل دریافت‌شده باشد اطلاعات جدول زیر را در متد IRDVerification باید ارسال شود.

آدرس درخواست:

https://dargaah.com/verification

آدرس درخواست به محیط SANDBOX:

https://dargaah.com/sandbox/verification

درصورتی که کاربر، تراکنش را با موفقیت انجام داده‌باشد و کد "100" در مرحله قبل دریافت‌شده باشد، باید اطلاعات جدول زیر، در آدرس بالا ارسال شود.

نام فیلد نوع توضیحات
merchantID String مرچنت کد دریافتی داخل پنل کاربری برای اتصال به درگاه بانکی (مقدار این پارامتر برای محیط تست برابر با TEST می باشد.)
authority String شناسه تراکنش
amount Integer مبلغ تراکنش به ریال، بدون اعشار و بزرگتر یا مساوی 10,000
orderId String شماره سفارش شما

در نهایت داده‌های دریافتی به شرح زیر می‌باشد:

نام فیلد نوع توضیحات
status Integer وضعیت تایید تراکنش. مقدار "100" برابر با تاییدیه موفق می‌باشد
message String پیام مربوط به وضعیت تایید تراکنش
refId String شماره پیگیری تراکنش
orderId String شماره سفارش شما
cardNumber String شماره کارت پرداخت کننده تراکنش

نشان اعتماد ایران درگاه :

‌با توجه به لزوم جلب اعتماد مشتریان جهت انجام پرداختی امن و سریع، می‌توانید با قراردادن کد زیر در قسمتی از وبسایت خود، که برای کاربران قابل مشاهده باشد (مانند فوتر وبسایت)، مشتریان خود را از پردازش پرداخت توسط ایران درگاه، مطمئن سازید.

<

script src="https://trust.irandargah.com/index.js"

>

جدول وضعیت‌ها :

200 اتصال به درگاه بانک با موفقیت انجام ‌شده‌است.
201 در حال پرداخت در درگاه بانک.
100 تراکنش با موفقیت انجام ‌شده‌‌است.
101 تراکنش قبلا verify شده‌است.
404 تراکنش یافت نشد.
403 کد مرچنت صحیح نمی‌باشد.
1- کاربر از انجام تراکنش منصرف‌ شده‌است.
2- اطلاعات ارسالی صحیح نمی‌باشد.
10- مبلغ تراکنش کمتر از 10,000 ریال است.
11- مبلغ تراکنش با مبلغ پرداخت، یکسان نیست. مبلغ برگشت‌خورد.
12- شماره کارتی که با آن، تراکنش انجام ‌شده‌است با شماره کارت ارسالی، مغایرت دارد. مبلغ برگشت‌خورد.
13- تراکنش تکراری است.
20- شناسه تراکنش یافت‌‌نشد.
21- مدت زمان مجاز، جهت ارسال به بانک گذشته‌است.
22- تراکنش برای بانک ارسال شده‌است.
23- خطا در اتصال به درگاه بانک.
30- اشکالی در فرایند پرداخت ایجاد ‌شده‌است.مبلغ برگشت خورد.
31- خطای ناشناخته