درگاه پرداخت زیبال

آخرین به‌روزرسانی :‌ 20 تیر 1399

مقدمه

به راهنمای سرویس درگاه پرداختی اینترنتی (IPG) زیبال خوش آمدید. این مستندات جهت آسانی استفاده شما از سرویس‌های زیبال جمع آوری شده‌اند. در صورت بروز هر گونه سوال با تیم فنی زیبال تماس بگیرید. وظیفه همکاران ما پاسخ به پیام‌های شما در اسرع وقت می‌باشد.

لطفا قبل از پیاده‌سازی به نکات زیر توجه نمایید:

  • API‌ های زیبال RESTful می‌باشند و درخواست‌ها و پاسخ‌ها به صورت JSON‌ رد و بدل می‌شوند.
  • زیبال تنها به درخواست‌هایی که تحت دامنه https ارسال می‌شوند پاسخ خواهد داد.
  • در صورت دریافت هر گونه خطا از جانب زیبال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط زیبال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!
  • یک حساب کاربری جهت تست تمام قابلیت‌ها و سرویس‌ها تهیه شده‌است. با قراردادن merchant : zibal می‌توانید از این حساب استفاده کنید.

مراحل راه‌اندازی

استفاده و راه‌اندازی سرویس درگاه پرداخت اینترنتی زیبال پیچیده نیست. تنها کافیست سه مرحله زیر را به‌درستی پیاده کنید!

1. درخواست پرداخت - Request

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

2. شروع پرداخت - Start

با ارسال trackId به این پایانه صفحه‌ی پرداخت برای شما نمایان می‌شود و شما آماده‌ی پرداخت هستید.

3. تایید پرداخت - Verify

زیبال وضعیت پرداخت هر سفارش را به آدرس callbackUrl ای که برای آن سفارش ثبت کرده‌اید ارسال می‌کند.
پس از آن نیاز است که شما متد تایید تراکنش را فرخوانی کنید.
تایید موفقیت‌آمیز بودن پرداخت از طریق این پایانه میسر است.

^_^

با طی شدن مسیر ذکر شده روند پرداخت یک سفارش پایان می‌یابد. مبلغ واریزی از طریق درگاه پرداخت اینترنتی بسته به تنظیمات حساب کاربری شما به حساب(های) تعیین‌شده یا کیف‌پول زیبال شما واریز می‌گردد.

اعتبارسنجی

زیبال از پارامتر merchant جهت اعتبارسنجی درگاه‌های موجود استفاده می‌کند.
این اطلاعات پس از ایجاد هر درگاه جدید در پنل کاربری زیبال موجود می‌باشند.

این امکان وجود دارد که درگاه خود را به IP (های) مشخصی محدود کنید.

در صورتی که نیاز به ابطال این اطلاعات دارید و یا این اطلاعات را از دست داده‌اید، با ما تماس بگیرید.

حساب تستی

پیش از راه‌اندازی و فعال‌سازی درگاه شما می‌توانید با قراردادن merchant : zibal تمام امکانات و سرویس‌ها را آزمایش کنید.

تمامی درخواست‌های ارسالی به زیبال بایستی حاوی اطلاعات احراز هویت باشند :
{
    "merchant": "zibal",
    // OTHER FIELDS
}

درخواست پرداخت - Request

از این پایانه جهت ارسال اطلاعات سفارش و ثبت آن در سیستم زیبال استفاده کنید.

اطلاعات درخواست
https://gateway.zibal.ir/v1/request POST
بدنه درخواست
پارامتر ضروری ؟ نوع توضیحات
merchant بله رشته (String) ضروری جهت احراز هویت
amount بله عدد (Long) مبلغ کل سفارش (به ریال)
callbackUrl بله رشته (String) آدرسی از سایت پذیرنده که زیبال اطلاعات پرداخت را به آن ارسال خواهد کرد.
description خیر رشته (String) توضیحات مربوط به سفارش (در گزارشات مختلف نشان‌داده خواهند شد)
orderId خیر رشته (String) شناسه سفارش منحصربه‌فرد شما (اختیاری - در گزارشات استفاده می‌شوند)
mobile خیر رشته (String) با فرستادن شماره موبایل کاربران خود، شماره کارت‌های ثبت‌شده مشتریان در درگاه پرداخت جهت انتخاب ظاهر می‌شوند.
allowedCards خیر لیستی از String چنانچه تمایل دارید کاربر فقط از شماره کارت های مشخصی بتواند پرداخت کند لیست کارت (های) 16 رقمی را ارسال کنید.
linkToPay خیر Boolean در صورتی که درگاه شما دسترسی ارسال لینک کوتاه پرداخت را داشته باشد، با قراردادن این متغیر برابر با true لینک کوتاه پرداخت برای این تراکنش ساخته می‌شود. لازم به ذکر است در این حالت callbackUrl میتواند ارسال نشود.
sms خیر Boolean با قراردادن این متغیر برابر با true لینک کوتاه پرداخت به شماره mobile ارسالی در همین بدنه ارسال خواهد شد.
percentMode خیر 0 یا 1 در صورتی که نحوه تسهیم مبلغ شما به‌صورت درصدی می‌باشد، این مقدار را 1 ارسال کنید. (پیش‌فرض :‌ 0)
feeMode خیر int 0: کسر از تراکنش
1: کسر کارمزد از کیف پول متصل به درگاه در پرداختیاری پشتیبانی نمی شود
2: افزوده شدن مبلغ کارمزد به مبلغ پرداختی توسط مشتری
multiplexingInfos خیر آرایه لیستی از شی آیتم تسهیم

آیتم تسهیم (MultiplexingInfo)

تنها ارسال یکی از پارامترهای bankAccount,subMerchantId,walletID در هر آیتم تسهیم اجباری است.

پارامتر ضروری نوع توضیحات
bankAccount خیر String شماره شبای ذی نفع
subMerchantId خیر String شناسه ذی نفع
walletID خیر String شناسه کیف پول در پرداختیاری پشتیبانی نمی شود
amount بله Long مبلغ یا درصد
wagePayer خیر Boolean کارمزد از این آیتم گرفته شود؟
فقط در صورتیکه feeMode: 0 موثر است.
اگر مشخص نشود از ذی نفع اصلی با id: self کارمزد اخذ میگردد.
{
    "merchant": "zibal",
    "amount": 160000,
    "callbackUrl": "http://yourapiurl.com/callback.php",
    "description": "Hello World!",
    "orderId": "ZBL-7799",
    "mobile": "09123456789"
}
{
    "merchant": "zibal",
    "amount": 3000,
    "callbackUrl": "http://zibal.ir/callback",
    "mobile": "09123456789",
    "description": "Hello World !",
    "orderId": "231",
    "feeMode":0,
    "multiplexingInfos":[
        {"amount":1000,"bankAccount": "IR540560004120002717448001"},
        {"walletID":1000,"walletID": 12185542112,"wagePayer":true},
        {"amount":1000,"subMerchantId":"x48mBx"}
      ]
  }
بدنه پاسخ
پارامتر توضیحات
trackId شناسه منحصربه‌فرد هر جلسه پرداخت درگاه پرداخت اینترنتی زیبال که استعلام وضعیت پرداخت و درخواست‌های گزارش‌گیری با استفاده از این شناسه امکان‌پذیر است.
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
payLink لینک کوتاه پرداخت
message پیغام حاوی نتیجه درخواست
{
    "trackId": 15966442233311,
    "result": 100,
    "message" : "success"
}
جدول result
کد توضیحات
100 با موفقیت تایید شد.
102 merchant یافت نشد.
103 merchant غیرفعال
104 merchant نامعتبر
201 قبلا تایید شده.
105 amount بایستی بزرگتر از 1,000 ریال باشد.
106 callbackUrl نامعتبر می‌باشد. (شروع با http و یا https)
113 amount مبلغ تراکنش از سقف میزان تراکنش بیشتر است.
107 percentMode نامعتبر می‌باشد. (تنها 0 و 1 قابل قبول هستند)
108 یک یا چند ذی‌نفع در multiplexingInfos نامعتبر می‌باشند. اطلاعات بیشتر
109 یک یا چند ذی‌نفع در multiplexingInfos غیرفعال می‌باشند. اطلاعات بیشتر
110 id = self در multiplexingInfos وجود ندارد.
111 amount با مجموع سهم‌ها در multiplexingInfos برابر نمی‌باشد.
112 موجودی کیف‌پول اصلی شما جهت ثبت این سفارش کافی نمی‌باشد. (در صورتی که feeMode == 1 )

شروع به پرداخت - Start

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

اطلاعات درخواست
https://gateway.zibal.ir/start/{{trackId}} GET
بدنه درخواست

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

درگاه پرداخت مستقیم - زیبال‌دایرکت

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

Callback

زیبال اطلاعات پرداخت یک سفارش را در زمان تغییر وضعیت به callbackUrl ثبت‌شده برای آن سفارش ارسال می‌کند.

این اطلاعات به صورت Query String و از طریق متد GET برای callbackUrl ارسال می‌شوند.

برای پایان دادن به جلسه پرداخت یک سفارش در صورت موفقیت‌آمیز بودن پرداخت، حتما از طریق پایانه‌ی تایید پرداخت‌ اقدام به تایید اطلاعات دریافتی نمایید.
بدنه Callback
پارامتر توضیحات
success در صورت موفقیت‌آمیز بودن تراکنش 1، در غیر این‌صورت 0 می‌باشد.
trackId شناسه پیگیری جلسه‌ی پرداخت
orderId شناسه سفارش ارسال شده در هنگام درخواست پرداخت (در صورت ارسال)
status وضعیت پرداخت (از طریق جدول وضعیت‌ها می‌توانید مقادیر status را مشاهده نمایید)
مثال:

https://yourcallbackurl.com/callback?trackId=9900&success=1&status=2&orderId=1

تایید پرداخت - Verify

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

تایید پرداخت

همان‌طور که قبلا اشاره شد زیبال با ارسال اطلاعات پرداخت به callbackUrl ثبت‌شده، شما را از وضعیت یک پرداخت مطلع می‌سازد. این پایانه جهت اطمینان زیبال از دریافت این اطلاعات توسط شما و خاتمه‌دادن پروسه پرداخت سفارش تعبیه شده‌است.

اطلاعات درخواست
https://gateway.zibal.ir/v1/verify POST
بدنه درخواست
پارامتر ضروری ؟ نوع توضیحات
merchant بله رشته (String) ضروری جهت احراز هویت
trackId بله عدد (Long) شناسه‌ی جلسه‌ی پرداختی که قصد تایید آن را دارید.
{
  "merchant": "zibal",
  "trackId": 15966442233311
}
بدنه پاسخ
پارامتر توضیحات
paidAt تاریخ پرداخت سفارش - به فرمت ISODate (در صورت موفقیت‌آمیز بودن پرداخت)
cardNumber شماره کارت پرداخت کننده (Mask شده)
status وضعیت پرداخت (از طریق جدول وضعیت‌ها می‌توانید مقادیر status را مشاهده نمایید)
amount مبلغ سفارش (به ریال)
refNumber شناسه مرجع تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
description توضیحات تراکنش (در صورت موفقیت‌آمیز بودن پرداخت)
orderId شناسه سفارش (در صورت موفقیت‌آمیز بودن پرداخت)
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام حاوی نتیجه درخواست
multiplexingInfos اطلاعات تسهیم تراکنش (در صورت تسهیم‌دار بودن)
{
    "paidAt": "2018-03-25T23:43:01.053000",
    "amount": 1600,
    "result": 100,
    "status": 1,
    "refNumber": 12312,
    "cardNumber": "62741****44",
    "description": "Hello World!",
    "orderId": "2211",
    "multiplexingInfos":[
        {"amount":900,"bankAccount": "IR540560004120002717448001"},
        {"amount":700,"bankAccount": "IR132000300120002722448001"}
      ]
    "message" : "success"
}
{
    "paidAt": "2018-03-25T23:43:01.053000",
    "amount": 1600,
    "result": 100,
    "status": 1,
    "refNumber": 12312,
    "description": "Hello World!",
    "cardNumber": "62741****44",
    "orderId": "2211",
    "message" : "success"
}
جدول result
کد توضیحات
100 با موفقیت تایید شد.
102 merchant یافت نشد.
103 merchant غیرفعال
104 merchant نامعتبر
201 قبلا تایید شده.
202 سفارش پرداخت نشده یا ناموفق بوده است. جهت اطلاعات بیشتر جدول وضعیت‌ها را مطالعه کنید.
203 trackId نامعتبر می‌باشد.

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

وضعیت توضیحات
-1 در انتظار پردخت
-2 خطای داخلی
1 پرداخت شده - تاییدشده
2 پرداخت شده - تاییدنشده
3 لغوشده توسط کاربر
4 ‌شماره کارت نامعتبر می‌باشد.
5 ‌موجودی حساب کافی نمی‌باشد.
6 رمز واردشده اشتباه می‌باشد.
7 ‌تعداد درخواست‌ها بیش از حد مجاز می‌باشد.
8 ‌تعداد پرداخت اینترنتی روزانه بیش از حد مجاز می‌باشد.
9 مبلغ پرداخت اینترنتی روزانه بیش از حد مجاز می‌باشد.
10 ‌صادرکننده‌ی کارت نامعتبر می‌باشد.
11 ‌خطای سوییچ
12 کارت قابل دسترسی نمی‌باشد.

نشان اعتماد زیبال


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

<script src="https://zibal.ir/trust/scripts/1.js">

پس از قراردادن این تکه کد، نشان اعتماد زیبال به شکل زیر در وبسایت شما نمایش داده خواهد شد.


اعلان تراکنش‌ها


شما می‌توانید جهت اطلاع از تراکنش‌های موفقیت‌آمیز از ربات تلگرامی زیبال استفاده کنید.

تنها کافی‌است وارد ZibalBot شوید و ربات را به حساب کاربری خود متصل نمایید تا تمامی تراکنش‌های تمامی درگاه‌های پرداخت شما، در لحظه به اطلاع شما برسند.

راهنمای مهاجرت


جهت مهاجرت به سرویس جدید، مراحل زیر را دنبال نمایید:

  1. آدرس پایانه request را به https://gateway.zibal.ir/v1/request تغییر دهید.
  2. آدرس پایانه verify را به https://gateway.zibal.ir/v1/verify تغییر دهید.
  3. اطلاعات ارسالی به آدرس callbackUrl را با استفاده از متد GET بخوانید.
  4. شما به سرویس جدید منتقل شدید!‌ :)