راهنمای خرید اقساطی بانک رفاه - سامانه بتا

راهنمای خرید اقساطی بانک مهر ایران - لند تک

راهنمای خرید اقساطی بانک تجارت - لند تک

راهنمای خرید اقساطی بانک ملی - لند تک

راهنمای خرید اقساطی بلو بانک - لند تک

راهنمای خرید اقساطی چکی

ثبت تبلیغ رایگان تبلیغ - آگهی

قیمت محصولات

همه محصولات

مستندات پلتفرم پرداخت در محل زیبال

آخرین به‌روزرسانی : ۲۰ شهریور ۱۴۰۱

مقدمه

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

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

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

احراز هویت

زیبال از پارامترهایmerchantIdوsecretKeyجهت احراز هویت مشتریان خود استفاده می‌کند. این اطلاعات پس از بررسی اطلاعات شما در هنگام ثبت‌نام از طریق پست الکترونیکی این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید برای شما ارسال شده اند.

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

تمامی درخواست‌های ارسالی به زیبال بایستی حاوی اطلاعات احراز هویت باشند :

{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    // OTHER FIELDS
}

سفارش (Order)

ثبت سفارش (Add Order)

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

اطلاعات درخواست

https://sandbox-api.zibal.ir/merchant/addOrderPOST

بدنه درخواست

پارامتر ضروری؟ نوع توضیحات
 
 
 
 
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId بله رشته (String) شناسه سفارش منحصربه‌فرد شما
amount بله عدد (Integer) مبلغ کل سفارش (به ریال)
callbackUrl بله رشته (String) آدرسی که زیبال اطلاعات پرداخت را به آن ارسال خواهد کرد.
description خیر رشته (String) توضیحات مربوط به سفارش (در گزارشات مختلف نشان‌داده خواهند شد).
mobile خیر رشته (String) شماره موبایل سفارش دهنده (در گزارشات مختلف نشان‌داده خواهند شد).
mobile خیر رشته (String) شماره موبایل سفارش دهنده (در گزارشات و دستگاه MPOS‌ مورد استفاده قرار می‌گیرد).
percentMode خیر 0 یا 1 در صورتی که نحوه تسهیم مبلغ شما به‌صورت درصدی می‌باشد، این مقدار را 1 ارسال کنید. (پیش‌فرض :‌ 0)
feeMode خیر 0 یا 1 در صورتی که درگاه شما دسترسی ارسال لینک کوتاه پرداخت را داشته باشد، با قراردادن این متغیر برابر با true لینک کوتاه پرداخت برای این تراکنش ساخته می‌شود. لازم به ذکر است در این حالتcallbackUrl میتواند ارسال نشود.
multiplexingInfos خیر آرایه اطلاعات تسهیم سفارش شما در قابل این آرایه به زیبال ارسال می‌شود. جهت مشاهده توضیحات بیشتر درباره این پارامتر به قسمت ذی‌نفع‌ها مراجعه نمایید.
تسهیم
درصورتی که تمایل به اضافه کردن سفارش تسهیم‌دار به زیبال را دارید، از صحت مبالغ وارد شده اطمینان حاصل نمایید.

جمع مبالغ موجود درmultiplexingInfosبایستی باamountارسال شده در سفارش برابر بوده و یا درصورتی که تسهیم شما از نوع درصدی است، جمع این درصدها می‌بایست 100 باشند.

تسهیم

در صورت عدم ارسالmultiplexingInfosدر درخواست ثبت سفارش، تمامی مبلغ سفارش به حسابselfواریز خواهد شد (حساب اصلی ثبت‌شده‌ی شما در زیبال). در غیر این‌صورت در اطلاعات تسهیم شما یک ذی‌نفع باid = selfمی‌بایست وجود داشته‌باشد که به معنی سهم شما از این سفارش خواهد بود.

مبلغ سهم ذی‌نفعselfمی‌بایست بیشتر از 10,000 ریال باشد.

نمونه JSON ارسالی شما برای این پایانه

بدنه پاسخ

پارامتر توضیحات
 
 
zibalId در صورت موفقیت‌آمیز بودن ثبت سفارش، این عدد به عنوان شناسه زیبال در پاسخ برگردانده می‌شود. این شناسه راه ارتباطی دستگاه‌های کارت‌خوان با سفارشات ثبت شده‌ی شما در سیستم زیبال است. با ورود این شناسه و یا اسکن بارکد مربوط به این شناسه اطلاعات پرداخت سفارش بر روی دستگاه کارت‌خوان نمایان خواهد شد. جهت دریافت بارکُد مربوط به این شناسه به قسمت بارکد در این سند مراجعه نمایید.
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده است.
message پیغام انگلیسی حاوی نتیجه درخواست
نمونه JSON پاسخ زیبال برای این پایانه

جدول result

کد توضیحات
 
 
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
3 orderIdمعتبر نمی‌باشد.
4 سفارشی با اینorderIdقبلا در زیبال ثبت‌شده‌است.
5 percentModeنامعتبر می‌باشد. (تنها 0 و 1 قابل قبول هستند)
6 amountبایستی بزرگتر از 10,000 ریال باشد.
7 یک یا چند ذی‌نفع درmultiplexingInfosنامعتبر می‌باشند.
8 یک یا چند ذی‌نفع درmultiplexingInfosنامعتبر می‌باشند.
9 id = selfدرmultiplexingInfosوجود ندارد.
10 amountبا مجموع سهم‌ها درmultiplexingInfosبرابر نمی‌باشد.
11 callbackUrlنامعتبر می‌باشد. (شروع با http و یا https)
18 موجودی کیف‌پول اصلی شما جهت ثبت این سفارش کافی نمی‌باشد. (در صورتی کهfeeMode == 1)

استعلام سفارش (Read Order)

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

استعلام سفارشات

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

اطلاعات درخواست

https://sandbox-api.zibal.ir/merchant/readOrderPOST

بدنه درخواست

پارامتر ضروری ؟ نوع توضیحات
 
 
 
 
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId یاzibalId رشته (String) شناسه سفارشی که قصد دریافت اطلاعات آن را دارید.
zibalId یاorderId رشته (String) شناسه زیبال سفارشی که قصد دریافت اطلاعات آن را دارید.
نمونه JSON ارسالی شما برای این پایانه

بدنه پاسخ

پارامتر توضیحات
 
 
zibalId شناسه زیبال این سفارش
orderId شناسه سفارش
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
status وضعیت سفارش. مشاهده جزئیات در جدول وضعیت سفارش‌ ها
refNumber (در صورتی که سفارش پرداخت‌شده باشد) - شماره مرجع پرداخت
createdAt تاریخ ثبت سفارش (به فرمت ISO-Date)
paidAt (در صورتی که سفارش پرداخت‌شده باشد) - تاریخ پرداخت (به فرمت ISO-Date)
canceledAt (در صورتی که سفارش لغو ‌شده باشد) - تاریخ لغو (به فرمت ISO-Date)
multiplexingInfos اطلاعات تسهیم سفارش. در این آرایه شماره شبای هر ذی‌نفع و سهم هر کدام از سفارش وجود دارند.
result جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
شماره شبا

در پاسخ درخواست‌های این پایانه و در آرایه‌یmultiplexingInfosبه‌جایidهر ذی‌نفع، شماره شبای آن‌ها در پارامترbankAccountآمده‌است.

Order Id - Zibal Id

در صورتی که هر دو پارامترorderIdوzibalIdرا در بدنه درخواست این پایانه ارسال نمایید، اطلاعات مربوط به شناسه سفارش (orderId) بازگردانده خواهد شد و شناسه زیبال در نظر گرفته نمی‌شود.

نمونه JSON پاسخ زیبال برای این پایانه

جدول Status Code

status وضعیت
 
 
0 در انتظار پرداخت
2 پرداخت‌شده
2 لغو شده

جدول result

کد توضیحات
 
 
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
12 یکی از پارامترهایorderIdوzibalIdبایستی ارسال شوند.

لغو سفارش (Cancel Order)

از این پایانه جهت لغو یک سفارش در سیستم زیبال استفاده کنید.

لغو سفارش

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

لغو سفارش

تنها سفارشات در انتظار پرداخت قابلیت لغو شدن دارند. از وضعیت سفارش قبل از استفاده از این پایانه اطمینان حاصل کنید.

اطلاعات درخواست

https://sandbox-api.zibal.ir/merchant/cancelOrderPOST

بدنه درخواست

پارامتر ضروری؟ نوع توضیحات
 
 
 
 
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId یاzibalId رشته (String) شناسه سفارشی که قصد لغو کردن آن را دارید.
zibalId یاorderId رشته (String) شناسه زیبال سفارشی که قصد لغو کردن آن را دارید.
نمونه JSON ارسالی شما برای این پایانه
Order Id - Zibal Id

در صورتی که هر دو پارامترorderIdوzibalIdرا در بدنه درخواست این پایانه ارسال نمایید، سفارش با شناسه سفارش (orderId) لغو خواهد شد و شناسه زیبال در نظر گرفته نمی‌شود.

ویرایش سفارش (Edit Order)

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

ویرایش سفارش

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

اطلاعات درخواست

https://sandbox-api.zibal.ir/merchant/editOrderPOST

بدنه درخواست

پارامتر ضروری؟ نوع توضیحات
 
 
 
 
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId بله رشته (String) شناسه سفارشی که قصد ویرایش آن را دارید.
amount بله عدد (Integer) مبلغ کل سفارش (به ریال)
callbackUrl بله رشته (String) آدرسی که زیبال اطلاعات پرداخت را به آن ارسال خواهد کرد.
mobile خیر رشته (String) شماره موبایل سفارش دهنده (در گزارشات و دستگاه MPOS‌ مورد استفاده قرار می‌گیرد).
description خیر رشته (String) توضیحات مربوط به سفارش (در گزارشات مختلف نشان‌داده خواهند شد).
percentMode بله 0 یا 1 در صورتی که نحوه تسهیم مبلغ شما به‌صورت درصدی می‌باشد، این مقدار را 1 ارسال کنید. (پیش‌فرض :‌ 0)
feeMode بله 0 یا 1 در صورتی که مایل هستید زیبال کارمزد خود را از روی کیف‌پول اصلی شما برداشت نماید این مقدار را 1 ارسال کنید. در غیر این‌صورت کارمزد زیبال از مبلغ کنونی سفارش (amount) کسر خواهد شد. (پیش‌فرض :‌ 0)
multiplexingInfos خیر آرایه اطلاعات تسهیم سفارش شما در قابل این آرایه به زیبال ارسال می‌شود. جهت مشاهده توضیحات بیشتر درباره این پارامتر به قسمت ذی‌نفع‌ها مراجعه نمایید.
ویرایش سفارش

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

نمونه JSON ارسالی شما برای این پایانه

بدنه پاسخ

پارامتر توضیحات
 
 
zibalId شناسه زیبالسفارش ویرایش شده.
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
نمونه JSON پاسخ زیبال برای این پایانه

جدولresult

کد توضیحات
 
 
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
3 سفارشی باorderIdارسالی شما در سیستم زیبال موجود نمی‌باشد.
5 percentModeنامعتبر می‌باشد. (تنها 0 و 1 قابل قبول هستند)
6 amountبایستی بزرگتر از 10,000 ریال باشد.
7 یک یا چند ذی‌نفع درmultiplexingInfosنامعتبر می‌باشند. اطلاعات بیشتر
8 یک یا چند ذی‌نفع درmultiplexingInfosغیرفعال می‌باشند. اطلاعات بیشتر
9 id = selfدرmultiplexingInfosوجود ندارد.
10 amountبا مجموع سهم‌ها درmultiplexingInfosبرابر نمی‌باشد.
11 callbackUrlنامعتبر می‌باشد. (شروع با http و یا https)
18 موجودی کیف‌پول اصلی شما جهت ثبت این سفارش کافی نمی‌باشد. (در صورتی کهfeeMode == 1)

ذی‌نفع‌ها

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

در صورت توجه در پایانه‌ی ثبت سفارش شماره شبای ذی‌نفع برای زیبال ارسال نشده بلکه یکidبه همراه مبلغ سهم در قالب یک شیء JSON در آرایهmultiplexingInfosارسال شده‌است.

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

id = self

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

تعریف ذی‌نفع

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

اطلاعات درخواست

https://sandbox-api.zibal.ir/merchant/addSubMerchantPOST

بدنه درخواست

پارامتر ضروری ؟ نوع توضیحات
 
 
 
 
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
bankAccount بله رشته (String) شماره شبای ذی‌نفع در حال تعریف
name بله رشته (String) نام ذی‌نفع (شماره شبای ارسالی می‌بایست به این نام باشد. در غیر این‌صورت ذی‌نفع در حال تعریف غیرفعال خواهد ماند.)
callbackUrl خیر رشته (String) آدرسی که زیبال فعال/غیرفعال شدن این ذی‌نفع را به آن ارسال می‌کند.
نمونه JSON ارسالی شما برای این پایانه
تایید / رد شدن ذی‌نفع‌ها

پس از فراخوانی موفقیت‌آمیز این پایانه، وضعیت ذی‌نفع‌ها به در حال بررسی تغییر می‌کنند. کارشناسان زیبال با بررسی اطلاعات وارد شده نسبت به تایید / رد کردن ذی‌نفع‌های ثبت شده تا 72 ساعت اقدام خواهند کرد. این وضعیت‌ها در پنل کاربری شما قابل مشاهده خواهد بود.

بدنه پاسخ

پارامتر توضیحات
 
 
id شناسه‌ای که با ارسال آن به‌عنوانidدرmultiplexingInfosمی‌توانید دستور تسهیم را برای این ذی‌نفع صادر نمایید.‌
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
نمونه JSON پاسخ زیبال برای این پایانه

جدول result

کد توضیحات
 
 
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
11 callbackUrlنامعتبر می‌باشد. (شروع با http و یا https)
14 nameنامعتبر می‌باشد.
15 bankAccountنامعتبر می‌باشد. (شماره شبا حاوی 26 کاراکتر می‌باشد و با IR شروع می‌شود.)
16 bankAccountقبلا در بین ذی‌نفع‌های شما تعریف شده است. (در این صورتidذی‌نفع قبلی در پاسخ ارسال می‌گردد)

بدنه Callback

در صورتی که در بدنه‌ی پایانه‌ی تعریف ذی‌نفع callbackUrlصحیح وارد کرده باشید، زیبال تغییر وضعیت ذی‌نفع را از طریق ارسال اطلاعات به آن آدرس به اطلاع شما می‌رساند.

پارامتر توضیحات
 
 
id شناسه ذی‌نفع‌
name نام ذی‌نفع
bankAccount شماره شبای ذی‌نفع‌
isActive در صورت تایید ذی‌نفع 1 و در صورت رد شدن ذی‌نفع 0 ارسال می‌گردد.

Callback

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

اطلاعات ارسالی توسط زیبال در جدول زیر قابل مشاهده می‌باشد.

پارامتر توضیحات
 
 
zibalId شناسه‌ زیبال سفارش اعلامی
orderId شناسه سفارش اعلامی
refNumber شماره مرجع
payNumber شماره پیگیری
paidAt تاریخ و ساعت پرداخت (به فرمت ISO-Date)
  • در دسترس بودن سرویس اجرا شده شما بر رویcallbackUrlارسالی شما برای زیبال مهم می‌باشد. از این رو در جواب این اطلاعات سرویس شما می‌بایست JSON زیر را در جواب به زیبال بازگرداند.
  • در صورت بروز مشکلات و عدم امکان انجام این کار، زیبال این اطلاعات را در سیکل‌های مشخص مجددا برای شما ارسال می‌کند تا از دریافت این اطلاعات اطمینان حاصل نماید.
JSON بازگردانده شده توسط شما :

بارکد

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

اطلاعات درخواست

https://api.zibal.ir/merchant/generateBarcode?zibalId={{zibalId}}GET

این پایانه بارکد مربوط بهzibalIdارسالی شما را در قالب عکس jpg بازمی‌گرداند.

از آنجایی که روش کار این پایانهGETمی‌باشد، با قراردادن این URL در src تگ img نیز می‌توانید به آسانی به آن دسترسی داشته باشید.

مثال


<img src='https://api.zibal.ir/merchant/generateBarcode?zibalId=727'>

نمونه‌کدها

پرستاشاپ - تا نسخه 1.6

ASP.NET

ووکامرس

گرویتی‌فرم

 

 منبع : https://zibal.ir