مستندات نرم‌افزار دستگاه کارتخوان موبایلی (MPOS)

آخرین به روز رسانی :‌ 8 اسفند 1398

مقدمه

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

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

  • از صحت پیاده‌سازی سرویس پرداخت در محل زیبال اطمینان حاصل نمایید. مستندات و راهنمای استفاده از این سرویس را از اینجا می‌توانید مشاهده نمایید.
  • پارامتر ارسالی برنامه‌ی شما در این SDK، تنها zibalId می‌باشد و اطلاعات سفارش مدنظر با توجه به اطلاعات ثبت‌شده در پایانه addOrder سرویس پرداخت‌درمحل بر روی دستگاه نمایان خواهد شد.
  • تمامی نمونه‌کدهای استفاده‌شده در این سند در سورس‌کد اپلیکیشن تستی زیبال موجود در گیت‌هاب وجود دارند.
  • در صورت دریافت هر گونه خطا از جانب زیبال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط زیبال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!

دستگاه‌های MPOS پشتیبانی شده

نرم‌افزار زیبال با دستگاه‌های زیر هماهنگ شده و قابل ارائه می‌باشد. جهت تامین دستگاه‌ها، با ما تماس بگیرید

Castles

Spectra

Pax

اضافه کردن فایل AAR

فایل AAR

جهت افزودن یک کتابخانه به پروژه اندروید می‌توانید از فایل‌های ‌AAR (Android Archive File) استفاده نمایید.

ما نیز SDK اتصال به دستگاه را به صورت یک فایل AAR ارائه می‌دهیم.

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

اپلیکیشن تستی زیبال


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

صفحه اصلی این اپلیکیشن به صورت زیر است:


حال به شرح هر یک از قابلیت‌های درون این اپلیکیشن تستی با ارائه نمونه کد مربوط به هر بخش می‌پردازیم.


سفارش

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

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

بدنه درخواست
پارامتر نوع توضیحات
zibalId String شناسه زیبال سفارش مد نظر جهت پرداخت

این ارتباط به شکل زیر و از طریق ساخت یک Intent و قراردادن شناسه زیبال در داده‌های آن صورت می‌گیرد.


در صورت صحت شناسه زیبال و مطابقت آن با سفارش‌های ثبت‌شده شما و برقراری ارتباط بلوتوث با MPOS، مبلغ سفارش بر روی دستگاه MPOS‌ نمایان می شود.

بازگشت پرداخت

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

بدنه پاسخ
پارامتر نوع توضیحات
zibalId String شناسه زیبال سفارش پرداخت‌شده
refNumber String شناسه ارجاع بانکی تراکنش
amount String مبلغ تراکنش

نکته‌ی بسیار مهم!

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


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

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

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

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