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

آخرین به‌روزرسانی : ۷ اسفند ۱۴۰۱

مقدمه

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

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

تمامی درخواست‌های شما از طریق بخش توسعه‌دهندگان - فراخوانی‌ها قابل مشاهده هستند.
API‌ های زیبال RESTful می‌باشند و درخواست‌ها و پاسخ‌ها به صورت JSON رد و بدل می‌شوند.
Status Code تمامی درخواست‌های موفق،200و تمامی درخواست‌های نامعتبر400و خطاهای داخلی سرور زیبال500می‌باشد که در این صورت شما می‌توانید با توجه بهmessageوresultو بررسی پارامترهای ارسالی، علت بروز خطا را دریابید.
زیبال تنها به درخواست‌هایی که از طرف IP های اعلامی شما ارسال شوند پاسخ خواهد داد.
در صورت دریافت هر گونه خطا از جانب زیبال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط زیبال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!
تیم فنی زیبال از طریق بخش پشتیبانی سایت، چت آنلاین و ایمیلاین آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید به سوالات شما در سریعترین زمان ممکن پاسخ خواهد داد.

مستندات APIها

احراز هویت

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

به این ترتیب تمامی درخواست‌های شما بایستی حاوی هدر به شکل زیر باشد:Authorization: Bearer {{ACCESS TOKEN}}

شما میتوانید با مراجعه به حساب کاربری/توسعه دهندگان/گزینه API Token ها، ACCESS TOKEN مربوط به خود را ایجاد نمایید.

هر پنل کاربری می‌تواند بینهایت ACCESS TOKEN از زیبال با دسترسی به API های متفاوت دریافت کند.

امکان محدودسازی برای IP های دلخواه و همچنین ایجاد محدودیت در سطح دسترسی ACCESS TOKEN ها با مراجعه به پنل کاربری امکان پذیر می‌باشد.

کیف پول

لیست کیف پول‌ها

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

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

https://api.zibal.ir/v1/wallet/list GET

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	لیستی از شیءwallet	آرایه‌ای حاوی اطلاعات کیف‌ پول‌ها

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

ایجاد کیف پول

از این پایانه می‌توانید جهت ایجاد یک کیف پول استفاده نمایید.

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

https://api.zibal.ir/v1/wallet/create POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

name	String	بله	اسم کیف پول

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

بدنه پاسخ

پارامتر	نوع	توضیحات

name	String	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	wallet	اطلاعات کیف‌پول

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

دریافت موجودی

از این پایانه می‌توانید جهت استعلام موجودی یک کیف پول استفاده نمایید.

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

https://api.zibal.ir/v1/wallet/balance POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

id	int	بله	شناسه کیف پول

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	wallet	اطلاعات و موجودی کیف‌پول درخواستی

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

ثبت درخواست تسویه

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

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

https://api.zibal.ir/v1/wallet/checkout POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

amount	long	بله	مبلغ تسویه (به ریال)
id	int	بله	شناسه کیف پول درخواستی جهت کسر وجه
subMerchantId	String	یا bankAccount	شناسه ذی‌نفع مقصد که از قبل در زیبال تعریف کردید و تایید شده است.
bankAccount	String	یا subMerchantId	شبا ذی‌نفع مقصد که از قبل در زیبال تعریف کردید و تایید شده است.
checkoutDelay	int	خیر	تعداد روزهای تاخیر تسویه 0 : برای تسویه در نزدیک ترین سیکل ممکن -1 : برای ارسال لحظه ای درخواست به بانک پیشفرض: ۱ روز بعد
uniqueCode	String	خیر	شناسه یکتا به ازای هر تسویه یکتا. این شناسه برای درخواست‌‌های تسویه از یک کیف پول، یکتا است و در صورتی که دو بار یک شناسه در درخواست تسویه ارسال شود، زیبال درخواست دوم را نمی‌پذیرد.
bank	String	خیر	از موجودی کدام بانکِ کیف پول تسویه انجام شود؟ smart: خودکار (در این حالت ابتدا بانک حساب مقصد که امکان انتقال وجه درون بانکی دارد انتخاب می شود در غیر اینصورت بانکی که بیشترین موجودی را دارد انتخاب می شود. saman: بانک سامان ayandeh: بانک آینده پیشفرض: مقداری که در پنل کاربری قسمت تنظیمات بانک وارد کرده اید. توجه: موجودی کیف پول در هر بانک از پایانه دریافت موجودی قابل دریافت است.
ledgerId	String	خیر	شناسه ledger مربوط به این تسویه - با موفق بودن تسویه، مبلغ این تسویه از موجودی این ledger کسر خواهد شد.

در صورتیکه کیف پول‌های غیر پرداختیاری checkoutDelay = -1 ارسال شود همان لحظه درخواست پایا به بانک مقصد ارسال می‌شود.
تسویه‌های غیر پرداختیاری با checkoutDelay = -1 امکان لغو ندارند.
دو قابلیت بالا در صورت درخواست کاربر و تحت شرایطی امکان فعال شدن روی کیف پول را دارد.
در کیف پول پرداختیاری پارامتر checkoutDelay را ارسال نکنید تا زیبال در نزدیک ترین زمان ممکن تسویه را انجام دهد.
در کیف پول پرداختیاری حداکثر امکان تسویه با 8 شماره شبا در یک روزکاری امکان پذیر است.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

result	int	نتیجه درخواست
message	string	پیغام حاوی نتیجه درخواست
data	جزئیات صف تسویه	می‌توانید ازidارسالی جهت لغو درخواست استفاده نمایید.

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

ثبت درخواست تسویه بدون نیاز به ثبت ذی‌نفع

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

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

https://api.zibal.ir/v1/wallet/checkout/plus POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

amount	long	بله	مبلغ تسویه (به ریال)
id	int	بله	شناسه کیف پول درخواستی جهت کسر وجه
bankAccount	String	بله	شماره شبای مقصد
checkoutDelay	int	خیر	تعداد روزهای تاخیر تسویه 0 : برای تسویه در نزدیک ترین سیکل ممکن -1 : برای ارسال لحظه ای درخواست به بانک پیشفرض: ۱ روز بعد
uniqueCode	String	خیر	شناسه یکتا به ازای هر تسویه یکتا. این شناسه برای درخواست‌‌های تسویه از یک کیف پول، یکتا است و در صورتی که دو بار یک شناسه در درخواست تسویه ارسال شود، زیبال درخواست دوم را نمی‌پذیرد.
bank	String	خیر	از موجودی کدام بانکِ کیف پول تسویه انجام شود؟ smart: خودکار (در این حالت ابتدا بانک حساب مقصد که امکان انتقال وجه درون بانکی دارد انتخاب می شود در غیر اینصورت بانکی که بیشترین موجودی را دارد انتخاب می شود. saman: بانک سامان ayandeh: بانک آینده پیشفرض: مقداری که در پنل کاربری قسمت تنظیمات بانک وارد کرده اید. توجه: موجودی کیف پول در هر بانک از پایانه دریافت موجودی قابل دریافت است.
ledgerId	String	خیر	شناسه ledger مربوط به این تسویه - با موفق بودن تسویه، مبلغ این تسویه از موجودی این ledger کسر خواهد شد.

برای این که تسویه حساب شما در اولین فرصت ممکن تسویه شود مقدار checkoutDelay را ارسال نکنید و یا null ارسال کنید.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

result	int	نتیجه درخواست
message	string	پیغام حاوی نتیجه درخواست
data	جزئیات صف تسویه	می‌توانید ازidارسالی جهت لغو درخواست استفاده نمایید.

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

لغو تسویه

از این پایانه می‌توانید جهت لغو درخواست‌های تسویه استفاده نمایید.

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

https://api.zibal.ir/v1/wallet/checkout/cancel POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

checkoutQueueId	string	بله	id تسویه که در متد تسویه کیف پول دریافت کردید

بدنه پاسخ

پارامتر	نوع	توضیحات

result	int	نتیجه درخواست
message	string	پیغام حاوی نتیجه درخواست

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

استعلام کارمزد تسویه

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

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

https://api.zibal.ir/v1/wallet/checkout/wage POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

amount	long	بله	مبلغ تسویه (به ریال)
id	int	بله	شناسه کیف پول درخواستی جهت تسویه
checkoutDelay	int	خیر	تعداد روزهای تاخیر تسویه (در صورت داشتن دسترسی : 0 : برای تسویه در همان روز؛ -1 : برای تسویه لحظه‌ای پایا)

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

بدنه پاسخ

پارامتر	نوع	توضیحات

result	int	نتیجه درخواست
message	string	پیغام حاوی نتیجه درخواست
data	کارمزد تسویه

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

استرداد

از این پایانه می‌توانید جهت استرداد وجه استفاده کنید.

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

https://api.zibal.ir/v1/wallet/refund POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

trackId	int	بله	شناسه تراکنش موفق درگاه پرداخت زیبال
amount	int	خیر	مبلغ مورد نظر به ریال برای ریفاند که باید حتما کوچک تر یا مساوی مبلغ تراکنش باشد حداکثر مبلغ ۱۵۰.۰۰۰.۰۰۰ ریال میتواند باشد
description	string	خیر	description توضیحات استرداد وجه
wageMode	int	خیر	نحوه کسر کارمزد استرداد وجه کسر از وجه بازگشتی : 1 کسر از کیف پول کارمزد : 2 پیشفرض: کسر از کیف پول کارمزد
ledgerId	String	خیر	شناسه ledger مربوط به این استرداد - با موفق بودن استرداد، مبلغ این استرداد از موجودی این ledger کسر خواهد شد.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

refundId	string	شناسه پیگیری ریفاند که بعدا توسط آن می‌توانید آخرین اطلاعات و وضعیت ریفاند را استعلام بگیرید
message	string	پیغام حاوی نتیجه درخواست
result	int	کد نتیجه درخواست اگر result==1 باشد درخواست ریفاند موفق ثبت شده است.

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

استعلام‌ وضعیت‌ در‌ دسترس‌ بودن‌ بانک‌ها ‌برای‌ تسویه‌آنی

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

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

https://api.zibal.ir/api/site-info/bank-availability/list GET

بدنه پاسخ

پارامتر	نوع	توضیحات

data	object	وضعیت در‌ دسترس‌ بودن‌ بانک‌ها را برای تسویه‌آنی به تفکیک هر بانک اعلام میکند.

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

گزارشات

گزارش تسویه

گزارش واریزی‌ها

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

https://api.zibal.ir/v1/report/checkout POST

بدنه درخواست

پارامتر	نوع	اجباری	مقدار پیشفرض	توضیحات

fromDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	تسویه‌های بعد از این تاریخ در پاسخ ارسال می‌شوند
toDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	تسویه‌های قبل از این تاریخ در پاسخ ارسال می‌شوند
page	int	خیر	1	شماره صفحه (از 1 شروع می‌شود)
size	int	خیر	100	تعداد گزارشات در هر صفحه
subMerchants	لیستی ازفیلتر ذی‌نفع‌ها	خیر	[]	در صورت ارسال این پارامتر، گزارشات تسویه با ذی‌نفع‌های ارسالی در پاسخ ارسال می‌شوند
transactionTrackId	long	خیر	-	جستجوی تسویه مربوط به یک تراکنش درگاه با trackId یا شماره تراکنش
transactionZibalId	long	خیر	-	جستجوی تسویه مربوط به یک تراکنش پرداخت در محل با zibalId
showWalletToWallet	boolean	خیر	-	تراکنش‌های کیف‌پول به کیف‌پول نیز نمایش داده شوند یا خیر
ledgerId	String	خیر	-	شناسه ledger جهت مشاهده تسویه‌های انجام شده
verbose	boolean	خیر	false	در صورت true بودن این پارامتر، آرایهdetailsارسال می‌شود.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
total	int	تعداد کل نتایج
data	لیستی از شیءتسویهیاکیف‌پول به کیف‌پول	اطلاعات تسویه

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

صف تسویه

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

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

https://api.zibal.ir/v1/report/checkout/queue POST

بدنه درخواست

پارامتر	نوع	اجباری؟	مقدار پیشفرض	توضیحات

subMerchants	لیستی ازفیلتر ذی‌نفع‌ها	خیر	[]	در صورت ارسال این پارامتر، صف تسویه با ذی‌نفع‌های ارسالی در پاسخ ارسال می‌شوند.
verbose	boolean	خیر	false	در صورت true بودن این پارامتر، اطلاعات اضافی ذی‌نفع (nameوid) در شیءsubMerchantو همچنین details ارسال می‌شود.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	لیستی از شیءصف تسویه	اطلاعات صف تسویه

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

استعلام تسویه

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

https://api.zibal.ir/v1/report/checkout/inquire POST

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات

checkoutRequestId	String	یا uniqueCode	شناسه رهگیری تسویه
uniqueCode	String	یا checkoutRequestId	شناسه یکتا به ازای هر تسویه یکتا. این شناسه برای درخواست‌‌های تسویه از یک کیف پول، یکتا است و در صورتی که دو بار یک شناسه در درخواست تسویه ارسال شود، زیبال درخواست دوم را نمی‌پذیرد.
walletId	String	بله	شناسه کیف‌پول مبدا

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	وابسته به وضعیت تسویه	پاسخ استعلام تسویه

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

گزارش تراکنش های درگاه پرداخت

‌از این پایانه می‌توانید جهت دریافت گزارشات هر درگاه پرداخت استفاده نمایید.

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

https://api.zibal.ir/v1/gateway/report/transaction POST

بدنه درخواست

پارامتر	نوع	اجباری؟	مقدار پیشفرض	توضیحات

merchantId	String	بله	-	کد مرچنت درگاه مورد نظر
fromDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	تسویه‌های بعد از این تاریخ در پاسخ ارسال می‌شوند
toDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	تسویه‌های قبل از این تاریخ در پاسخ ارسال می‌شوند
page	int	خیر	1	شماره صفحه (از 1 شروع می‌شود)
size	int	خیر	100	تعداد گزارشات در هر صفحه
verbose	boolean	خیر	false	در صورت true بودن این پارامتر، شماره کارت، توضیحات تراکنش، جزئیات تسهیم و تلفن همراه هم ارسال می‌شود.
trackId	long	خیر	-	فیلتر شناسه تراکنش
status	int	خیر	-	1: پرداخت موفق و verify شده 2: پرداخت موفق و verify نشده
orderId	String	خیر	-	فیلتر شماره سفارش ارسالی
mobile	String	خیر	-	فیلتر تلفن همراه
amount	Long	خیر	-	فیلتر مبلغ
cardNumber	String	خیر	-	جستجو بر اساس شماره کارت

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
total	int	تعداد کل نتایج
sum	Long	جمع کل مبلغ تراکنش ها
data	لیستی از شیءتراکنش درگاه آنلاین	آرایه‌ای حاوی اطلاعات تراکنش‌ها

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

گزارش تراکنش های سرویس پرداخت در محل

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

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

https://api.zibal.ir/v1/cod/report/transaction POST

بدنه درخواست

پارامتر	نوع	اجباری؟	مقدار پیشفرض	توضیحات

zibalId	int	خیر	-	شناسه پرداخت تراکنش
fromDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	پرداخت‌های بعد از این تاریخ در پاسخ ارسال می‌شوند
toDate	String(ISO-Date) یا Long(Unix Timestamp)	خیر	-	پرداخت‌های قبل از این تاریخ در پاسخ ارسال می‌شوند
page	int	خیر	1	شماره صفحه (از 1 شروع می‌شود)
size	int	خیر	100	تعداد گزارشات در هر صفحه
verbose	boolean	خیر	false	در صورت true بودن این پارامتر، شماره کارت، توضیحات تراکنش، جزئیات تسهیم هم ارسال می‌شود.
status	int	خیر	-	فیلتر شناسه تراکنش
status	int	خیر	-	0: در انتظار پرداخت 1: پرداخت موفق و اعلام شده 2: سفارش لغو شده 3: پرداخت موفق و اعلام نشده
orderId	String	خیر	-	فیلتر شماره سفارش ارسالی
mobile	String	خیر	-	فیلتر تلفن همراه

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
total	int	تعداد کل نتایج
sum	Long	جمع کل مبلغ تراکنش ها
data	لیستی از شیءتراکنش پرداخت در محل	آرایه‌ای حاوی اطلاعات تراکنش‌ها

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

گزارش استرداد

‌از این پایانه می‌توانید جهت دریافت گزارشات استرداد وجه استفاده نمایید.

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

https://api.zibal.ir/v1/wallet/refund/inquiry POST

بدنه درخواست

پارامتر	نوع	اجباری؟	مقدار پیشفرض	توضیحات

walletId	String	بله	-	شناسه کیف پول مورد نظر
refundId	int	بله	-	شناسه استرداد که در پایانه درخواست ریفاند برگشت داده شده است
amount	String	خیر	-	اعمال فیلتر بر اساس مبالغ کمتر یا مساوی مقدار ارسالی
cardNumber	String	خیر	-	شماره کارت
iban	String	خیر	-	شماره شبا

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
data	شیءاسترداد	شیء ای حاوی اطلاعات استرداد

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

ذی‌نفع‌ها

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

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

تعریف ذی‌نفع

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

سرویس ویژه

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

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

https://api.zibal.ir/v1/subMerchant/create POST

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

bankAccount	بله	string	شماره شبای ذی‌نفع در حال تعریف
name	بله	string	نام ذی‌نفع (شماره شبای ارسالی می‌بایست به این نام باشد. در غیر این‌صورت ذی‌نفع غیرفعال خواهد ماند.)
callbackUrl	خیر	string	آدرسی که زیبال تغییر وضعیت این ذی‌نفع را به آن ارسال می‌کند.(بدنه callback)

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

تایید / رد شدن ذی‌نفع‌ها

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
subMerchant	ذی‌نفع	ذی‌نفع اضافه‌شده

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

بدنه callback

پارامتر	توضیحات

subMerchant	ذی‌نفع

لیست ذی‌نفع‌های ثبت‌شده

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

سرویس ویژه

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

https://api.zibal.ir/v1/subMerchant/list POST

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

subMerchant	خیر	فیلتر ذی‌نفع‌ها	لیست ذی‌نفع‌ها بر اساس این مقدار فیلتر می‌شوند
page	int	خیر	شماره صفحه (از 1 شروع می‌شود)
size	int	خیر	تعداد گزارشات در هر صفحه

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	لیستی ازذی‌نفع	لیست ذی‌نفع‌های اضافه‌شده
total	int	تعداد کل نتایج

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

ویرایش ذی‌نفع

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

سرویس ویژه

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

https://api.zibal.ir/v1/subMerchant/edit POST

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

id	بله	رشته (String)	شناسه‌ ذی‌نفعی که تمایل به ویرایش آن را دارید.
bankAccount	بله	رشته (String)	شماره شبای ویرایش‌ شده
name	بله	رشته (String)	نام ویرایش‌ شده

ویرایش ذی‌نفع

این پایانه تنها جهت ویرایش ذی‌نفع‌های غیرفعال استفاده می‌شود. ارسال حداقل یکی از دو پارامترnameوbankAccountجهت تغییر اجباری می‌باشد.

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data	ذی‌نفع	ذی‌نفع ویرایش‌شده

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

اشیا و مدل‌ها

کیف پول

پارامتر	نوع	توضیحات

id	int	شناسه هر کیف پول - این شناسه در پنل کاربری نیز قابل رویت می‌باشد
name	string	نام کیف پول
balance	long	موجودی کیف پول (به ریال)
withdrawableBalance	long	جمع قابل برداشت (برای تسویه لحظه ای) به ریال

صف تسویه

اطلاعات هر عضو صف تسویه در این شیء ارسال می‌شوند.

پارامتر	نوع	توضیحات

details	لیستی ازجزئیات صف تسویه	جزئیات هر درخواست تسویه (در صورتی کهverbose == trueارسال می‌شود)
amount	long	مبلغ تسویه (به ریال)
wage	long \| null	کارمزد تسویه
persianPredictedCheckoutDate	string	تاریخ شمسی پیش‌بینی شده واریز (بر اساس سیکل پایا و تنظیمات تسویه)
predictedCheckoutDate	string	تاریخ پیش‌بینی شده واریز (بر اساس سیکل پایا و تنظیمات تسویه) (فرمت : YYYY/MM/DD)
subMerchant	ذی‌نفع	ذی‌نفع تسویه (در صورتی کهverbose == falseتنهاbankAccountارسال می‌شود.)

کارمزد

کارمزد تسویه

پارامتر	نوع	توضیحات

wage	long \| null	کارمزد تسویه به ریال
sufficient	boolean	آیا موجودی کیف پول به همراه کارمزد برای انجام این تسویه کافی است یا نه.

تسویه

اطلاعات تسویه در این شیء ارسال می‌شوند.

پارامتر	نوع	توضیحات

details	لیستی ازجزئیات تسویه	جزئیات هر تسویه (در صورتی کهverbose == trueارسال می‌شود)
settlementDate	string (ISO-Date)	تاریخ واریز به فرمت ISO-Date
type	int	نوع تسویه3: تسویه به حساب بانکی4: تسویه به کیف‌پول
persianSettlementDate	string	تاریخ واریز به فرمت شمسی
refNumber	string	شناسه مرجع
amount	long	مبلغ تسویه (به ریال)
status	int	وضعیت تسویه (۰: موفق - ۱: برگشت‌خورده به حساب - ۲: اصلاح به کیف‌پول)
subMerchant	ذی‌نفع	ذی‌نفع تسویه (در صورتی کهverbose == falseتنهاbankAccountارسال می‌شود.)

کیف‌پول به کیف‌پول

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

پارامتر	نوع	توضیحات

details	لیستی ازجزئیات تسویه	جزئیات هر تسویه (در صورتی کهverbose == trueارسال می‌شود)
settlementDate	string (ISO-Date)	تاریخ واریز به فرمت ISO-Date
persianSettlementDate	string	تاریخ واریز به فرمت شمسی
refNumber	string	شناسه مرجع
amount	long	مبلغ تسویه (به ریال)
subMerchant	ذی‌نفع کیف‌پول	ذی‌نفع تسویه
sourceWalletID	string	شناسه کیف‌پول مبدا
sourceWalletName	string	نام کیف‌پول مبدا
destinationWalletID	string	شناسه کیف‌پول مقصد
destinationWalletName	string	نام کیف‌پول مقصد

جزئیات تسویه

هر تسویه‌حساب متشکل از یک یا چند درخواست تسویه می‌باشد که این درخواست‌ها در قالب این شیء و در آرایه‌یdetailsارسال می‌شوند.

پارامتر	نوع	توضیحات

createdAt	ISO-Date	تاریخ ایجاد تسویه یا انجام تراکنش
amount	long	مبلغ تسویه (ریال)
type	int	نوع:1 : تراکنش تسهیمی درگاه2 : تسویه کیف پول3 : تراکنش تسهیمی کارتخوان
transactionId	String	اگر تراکنش تسهیمی درگاه باشد مقدار trackId تراکنش درگاه و اگر تراکنش پرداخت در محل کارتخوان باشد مقدار zibalId برمیگردد
transactionOrderId	String	شناسه سفارش تراکنش که کاربر ارسال کرده است
description	String	توضیحات
ledgerId	String	شناسه ledger
subMerchant	ذی‌نفع	اطلاعات صاحب حساب مقصد (در صورت استفاده از تسویه بدون ثبت ذی‌نفع)

جزئیات صف تسویه

هر آیتم صف تسویه متشکل از یک یا چند درخواست تسویه می‌باشد که این درخواست‌ها در قالب این شیء و در آرایه‌یdetailsارسال می‌شوند.

پارامتر	نوع	توضیحات

id	string	شناسه تسویه (قابل استفاده برایلغو تسویه)
createdAt	String	تاریخ شمسی ایجاد آیتم تسویه
amount	long	مبلغ تسویه (ریال)
description	String	توضیحات
type	int	نوع:1 : تراکنش تسهیمی درگاه2 : تسویه کیف پول3 : تراکنش تسهیمی کارتخوان
transactionId	String	اگر تراکنش تسهیمی درگاه باشد مقدار trackId تراکنش درگاه و اگر تراکنش پرداخت در محل کارتخوان باشد مقدار zibalId برمیگردد
transactionOrderId	String	شناسه سفارش تراکنش که کاربر ارسال کرده است
ledgerId	String	شناسه ledger

ذی‌نفع

پارامتر	نوع	توضیحات

id	int	شناسه ذی‌نفع
bankAccount	string	شماره شبای ذی‌نفع
name	string	نام ذی‌نفع
status	int	0 در انتظار تایید1 تایید شده2 رد شده1- حذف شده

فیلتر ذی‌نفع‌ها

این شیء جهت فیلتر کردن گزارشات بر اساس ذی‌نفع‌ها مورد استفاده قرار می‌‌گیرد.
لازم به ذکر است ارسال تنها یکی از پارامترهایidیاbankAccountکافی است.

پارامتر	نوع	توضیحات

id	int	شناسه ذی‌نفع
bankAccount	string	شماره شبای ذی‌نفع

تراکنش پرداخت در محل

توجه کنید که برخی پارامترها فقط وقتی verbose == true باشد ارسال میشوند.

پارامتر	نوع	توضیحات	ارسال فقط در حالت verbose=true

amount	Long	مبلغ تراکنش (ریال)	-
zibalId	int	شناسه پرداخت	-
orderId	String	شماره سفارش فروشگاه شما	-
status	int	0: در انتظار پرداخت 1: پرداخت موفق و اعلام شده 2: سفارش لغو شده 3: پرداخت موفق و اعلام نشده	-
createdAt	ISO-Date	تاریخ و زمان ثبت سفارش	-
paidAt	ISO-Date	تاریخ و زمان پرداخت تراکنش	-
cancelledAt	ISO-Date	تاریخ و زمان لغو سفارش	-
refNumber	String	شناسه مرجع یکتای بانکی	-
multiplexingInfos	String	لیستی از شیآیتم تسهیم	بله
description	String	توضیحات	بله
cardNumber	String	شماره کارت mask شده پرداخت کننده	بله

تراکنش درگاه آنلاین

توجه کنید که برخی پارامترها فقط وقتی verbose == true باشد ارسال میشوند.

پارامتر	نوع	توضیحات	ارسال فقط در حالت verbose=true

amount	Long	مبلغ تراکنش (ریال)	-
trackId	Long	شناسه تراکنش	-
orderId	String	شماره سفارش فروشگاه شما	-
status	int	1: پرداخت موفق و verify شده 2: پرداخت موفق و verify نشده	-
paidAt	ISO-Date	تاریخ و زمان پرداخت تراکنش	-
refNumber	String	شناسه مرجع یکتای بانکی	بله
description	String	توضیحات	بله
mobile	String	تلفن همراه پرداخت کننده	بله
cardNumber	String	شماره کارت mask شده پرداخت کننده	بله
multiplexingInfos	String	لیستی از شیآیتم تسهیم	بله

آیتم تسهیم

این شیء اطلاعات تسهیم و مبلغ واریز شده بابت این تراکنش را به مشتری نشان میدهد.

پارامتر	نوع	توضیحات

id	int	شناسه ذی‌نفع در زیبال
bankAccount	string	شماره شبای ذی‌نفع
amount	long	مبلغ سهم ذی نفع
wallet	Integer	شماره آیدی کیف پول

*حداقل یکی از دو مقادیر آیدی کیف پول یا شماره شبا الزامی است

استرداد

این شیء اطلاعات استرداد را نشان میدهد.

پارامتر	نوع	توضیحات

refundId	String	شناسه استرداد
checkoutDetail	شیءواریز	شیء ای حاوی اطلاعات واریز
transactionDetail	شیءتراکنش درگاه	شیء ای حاوی اطلاعات تراکنش درگاه
statusEn	String	وضعیت درخواست استرداد PENDING: در انتظار پردازش ALLOCATED: پردازش شده در انتظار واریز DONE: پایانه یافته
status	int	وضعیت درخواست استرداد 0: در انتظار پردازش 1: پردازش شده در انتظار واریز 2: پایانه یافته

*حداقل یکی از دو مقادیر آیدی کیف پول یا شماره شبا الزامی است

صاحب حساب

این شیء اطلاعات صاحب حساب را نشان میدهد.

پارامتر	نوع	توضیحات

name	String	نام صاحب حساب
bankAccount	String	شماره شبا
bankName	String	نام بانک
deposit	String	شماره حساب

صاحب کارت

این شیء اطلاعات صاحب شماره کارت را نشان میدهد.

پارامتر	نوع	توضیحات

name	String	نام صاحب شماره کارت

کد پستی

این شیء اطلاعات کد پستی را نشان میدهد.

پارامتر	نوع	توضیحات

address	Object	شئ آدرس

آدرس

این شیء آدرس را نشان میدهد.

پارامتر	نوع	توضیحات

province	String	استان
town	String	شهر
district	String	منطقه
street	String	خیابان اصلی
street2	String	خیابان فرعی
number	String	پلاک
floor	String	طبفه
sideFloor	String	واحد
buildingName	String	نام ساختمان
description	String	توضیحات

جدول Result

Status Code تمامی درخواست‌های موفق،200و تمامی درخواست‌های ناموفق400,403,500می‌باشد.

عمومی

result	توضیحات

1	موفق
2	API Key به درستی ارسال نشده است.
3	API Key صحیح نیست.
4	اجازه دسترسی به این سرویس صادر نشده‌است.
5	callbackUrl نامعتبر است.
6	مقدار ورودی نامعتبر است
7	IP ارسال‌کننده درخواست نامعتبر می‌باشد.
8	API Key غیرفعال است.
9	حداقل مبلغ باید 1000 ریال باشد.
21	شماره شبای وارد شده معتبر نیست.( 26 کاراکتر و شروع با IR و بدون خط تیره (-) و فاصله)
29	موجودی کیف‌پول کارمزد برای این عملیات کافی نیست
44	با ورودی های داده شده شبای مورد نظر یافت نشد
45	سرویس دهنده ها برای استعلام در دسترس نیستند

کیف پول

result	توضیحات

10	کیف پول انتخاب شده وجود ندارد.
11	مبلغ درخواستی از موجودی کیف پول بیشتر است.
12	حداقل مبلغ تسویه 10000 ریال است.
13	تاخیر تسویه از حد مجاز اکانت شما کمتر است.
14	درخواست تسویه مورد نظر وجود ندارد.
15	این مقدار تاخیر تسویه برای حساب کاربری شما مجاز نمی‌باشد.
16	دسترسی این نوع درخواست تسویه برای کیف پول مورد نظر وجود ندارد.
17	امکان ثبت درخواست تسویه آنی برای مبالغ بیشتر از 100 میلیون تومان وجود ندارد.
18	مرچنت درگاه مورد نظر مورد یافت نشد و یا غیر فعال است.

ذی‌نفع

result	توضیحات

20	نام وارد نشده‌است.
21	شماره شبای وارد شده نامعتبر است (شروع با IR و 26 کاراکتر)
22	ذی‌نفع قبلا ثبت شده است.
23	ذی‌نفع نامعتبر است.
24	ذی‌نفع غیرفعال است.
25	امکان ویرایش ذی‌نفع فعال وجود ندارد.
26	مقدار اعتبار استعلام شبای شما به پایان رسیده است.

استرداد

result	توضیحات

50	تراکنشی یافت نشد.
51	کیف پول مورد نظر یافت نشد.
52	ریفاند این تراکنش در حال پردازش است.
53	ریفاند این تراکنش انجام شده است.
54	تراکنش درخواست شده موفق نبوده است.
55	مبلغ وارد شده از مبلغ تراکنش بیشتر است.
56	امکان ریفاند این تراکنش به دلیل عدم دسترسی به شماره کارت میسر نیست.
57	شماره کارت معتبر نیست.
58	موجودی کیف پول شما برای انجام این ریفاند کافی نیست.
59	مبلغ ریفاند از 1000 تومان کمتر است.
60	موجودی کیف پول شما برای کسر کارمزد این ریفاند کافی نیست.
61	مقدار refund باید از 15 میلیون تومان کمتر باشد.

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