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

نسخه آزمایشی

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

مقدمه

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

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

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

پنل کاربری

کیف پول‌ها

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

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

هر کیف پول قابلیت اتصال به درگاه پرداخت اینترنتی زیبال و پلتفرم پرداخت در محل زیبال را دارد.

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

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

با حساب اصلی و یا ذی‌نفع‌های* تایید شده‌ی خود تسویه نمایید.

این مبالغ در سیکل‌های پایا به حساب‌های مورد نظر شما واریز خواهند شد.

* ذی‌نفع‌ها

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

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

ذی‌نفع‌ها

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

صف تسویه

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

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

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

گزارش تسویه

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

مستندات APIها

احراز هویت

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

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

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

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

کیف پول

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

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

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

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

بدنه پاسخ

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

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

{
     "message": "موفق",
     "result": 1,
     "data": [
         {
            "name": "اصلی زیبال",
            "withdrawableBalance": 105000,
            "balance": 185000,
            "id": 1010101
         },
         {
            "balance": 954000,
            "withdrawableBalance": 105000,
            "name": "حقوق کارکنان",
            "id": 1010450
        }
     ]
}

ایجاد کیف پول

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

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

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

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات
name	String	بله	اسم کیف پول

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

{
    "name": "تستی"
}

بدنه پاسخ

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

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

{
         "message": "موفق",
         "result": 1,
         "data": [
             {
                 "balance": 185000,
                 "withdrawableBalance": 105000,
                 "name": "اصلی زیبال",
                 "id": 1010101
             }
         ]
    }

شارژ کیف پول

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

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

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

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات
id	int	بله	شناسه کیف پول
gatewayMerchant	String	بله	مرچنت درگاهی که قصد استفاده از آن را دارید
amount	long	بله	مبلغ
callbackUrl	String	بله	آدرس صفحه بازگشت
mobile	String	خیر	جهت نمایش شماره‌کارت های ذخیره شده کاربر در صفحه پرداخت
feeMode	int	خیر	نوع کسر کارمزد: `0` : کسر از تراکنش (پیشفرض) `1` : کسر از کیف پول متصل به درگاه `2` : برعهده پرداخت کننده

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

{
	"id": "10210",
	"amount": 10000,
	"callbackUrl": "http://localhost:8000/callback.php",
	"gatewayMerchant": "test",
	"mobile": "09120000000"
}

بدنه پاسخ

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

پس از دریافت trackId همانطور که در مستند درگاه پرداخت هم اشاره شده با ریدایرکت کردن کاربر به آدرس https://gateway.zibal.ir/start/{trackId} وارد صفحه درگاه پرداخت می شود. از این مرحله به بعد کلیه مراحل همانند درگاه پرداخت زیبال خواهد بود. (برای توضیحات بیشتر و استفاده از درگاه مستقیم لطفا به بخش مستند درگاه پرداخت مراجعه کنید.)

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

{
    "result": 1,
    "trackId": 3722194,
    "message": "success"
}

انتقال بین کیف پولی

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

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

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

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات
srcId	int	بله	شناسه کیف پول مبدأ
destId	int	بله	شناسه کیف پول مقصد
amount	long	بله	مبلغ

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

{
       	"srcId": 10210,
       	"destId": 10280,
       	"amount": 100000,
       }

بدنه پاسخ

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

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

{
           "result": 1,
           "trackId": "5db3fe0c47604a9371647610",
           "message": "success"
       }

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

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

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

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

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات
id	int	بله	شناسه کیف پول

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

{
    "id": 1010101
}

بدنه پاسخ

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

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

{
         "message": "موفق",
         "result": 1,
         "data": [
             {
                 "balance": 185000,
                 "withdrawableBalance": 105000,
                 "name": "اصلی زیبال",
                 "id": 1010101
             }
         ]
    }

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

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

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

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

بدنه درخواست

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

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

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


{
	"amount": 10000,
	"id": 10101,
	"bankAccount": "IR060180000000000000020600",
	"checkoutDelay": 1,
    "description": "تسویه بابت حقوق آقای فرهادی"

}

بدنه پاسخ

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

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


   {
    "data": {
        "createdAt": "2019-05-01T17:25:48.037370",
        "description": "تسویه بابت حقوق آقای فرهادی",
        "type": 2,
        "amount": 10000,
        "id": "xfg99754ae7abb06d63f1d60"
    },
    "message": "موفق",
    "result": 1
}

لغو تسویه

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

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

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

بدنه درخواست

پارامتر	نوع	اجباری؟	توضیحات
checkoutQueueId	string	بله	`id` تسویه که در متد تسویه کیف پول دریافت کردید

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


{
	"checkoutQueueId": "5cc976a1ae78bb61149cdc61"
}

بدنه پاسخ

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

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

{
    "message": "موفق",
    "result": 1
}

گزارشات

گزارش تسویه

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

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

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
verbose	boolean	خیر	false	در صورت true بودن این پارامتر، آرایه `details` ارسال می‌شود.

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

{
	"verbose": true,
	"page": 1,
	"size":10,
	"subMerchants": [
         {"id": "sjUEMh"},
         {"bankAccount":"IR110011001100110011001100"}
    ],
	"fromDate": "2017-10-10T03:45:00",
	"toDate": 1547079300000
}

بدنه پاسخ

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

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

{
    "message": "موفق",
    "result": 1,
    "total": 4,
    "data": [

/* IN CASE verbose == TRUE */
        {
            "details": [
                {
                    "createdAt": "2018-12-07T19:56:40",
                    "amount": 350000,
                    "type": 3,
                    "transactionId":"123",
                    "transactionOrderId":"123",
                    "description": "تراکنش کارتخوان",
                },
                {
                    "createdAt": "2018-12-10T23:31:22",
                    "amount": 475000,
                    "transactionId":"123",
                    "transactionOrderId":"123",
                     "type": 3,
                    "description": "",
                }
            ],
            "settlementDate": "2018-12-29T15:45:00.691000",
            "persianSettlementDate": "1397/10/08 عصر",
            "refNumber": "971008062240101",
            "amount": 825000,
            "subMerchant": {
                "id": "sjUEMh",
                "bankAccount": "IR001100110011001100110011",
                "name": "همایون شجریان",
                "status": 1
            }
        },


/* IN CASE verbose == FALSE */
        {
            "settlementDate": "2018-12-29T15:45:00.571000",
            "persianSettlementDate": "1397/10/08 عصر",
            "refNumber": "9710080122411111",
            "amount": 1880000,
            "details":[],
            "subMerchant": {
                "bankAccount": "IR110011001100110011001100",
                "name": "همایون شجریان",
                "id": "sjUEMh",
                "status": 1
            }
        }
     ]
 }

صف تسویه

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

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

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

بدنه درخواست

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

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

{
	"verbose": false,
	"subMerchants": [
         {"id": "sjUEMh"},
         {"bankAccount":"IR110011001100110011001100"}
    ]
}

بدنه پاسخ

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

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

{
    "data": [
/* IN CASE DEEP == TRUE */
        {
            "amount": 888000000,
            "subMerchant": {
                "id": "9Sv12t",
                "bankAccount": "IR110011001100110011001100",
                "name": "فاطمه معتمدآریا",
            },
            "persianPredictedCheckoutDate": "1397/10/09",
            "predictedCheckoutDate": "2018/12/30",
             "details": [
                {
                    "type": 3,
                    "amount": 202000,
                    "createdAt": "1398/01/29-16:33:44",
                    "description": ""
                },
                {
                    "type": 2,
                    "amount": 500000,
                    "createdAt": "1398/01/29-15:05:49",
                    "description": "توضیح تسویه کیف پول"
                }
            ]
        },

/* IN CASE DEEP == FALSE */
        {
            "amount": 7209000,
            "subMerchant": {
                "bankAccount": "IR001100110011001100110011",
            },
            "details" : [],
            "persianPredictedCheckoutDate": "1397/10/09",
            "predictedCheckoutDate": "2018/12/30"
        }
    ],
    "message": "موفق",
    "result": 1
}

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

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

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

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 ارسالی شما برای این پایانه

{
	"size": 10,
	"page": 1,
	"merchantId": "5b86d252f92ea1048015ae35",
	"verbose": false
}

بدنه پاسخ

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

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

{
   {
    "total": 1,
    "result": 1,
    "sum": 1000000
    "message": "موفق",
    "data": [
        /* IN CASE verbose == TRUE */

        {
            "cardNumber": "504706******8732",
            "amount": 1000000,
            "trackId": 123456,
            "orderId": "1234",
            "description": "پرداخت کاربر 11",
            "status": 1,
            "mobile": "09120000000",
            "multiplexingInfos": "multiplexingInfos": [
                {
                    "amount": 600000,
                    "bankAccount": "IR000100000000010988060005",
                    "id": "self"
                },
                {
                    "amount": 400000,
                    "bankAccount": "IR000000000000000010500000",
                    "id": "t0y4M0"
                }
            ],
            "paidAt": "2019-04-18T18:28:39.342000",
            "refNumber": "12355070545"
        },


        /* IN CASE verbose == FALSE */

        {
            "amount": 1000000,
            "trackId": 3719987,
            "orderId": "",
            "status": 1,
            "paidAt": "2019-04-18T18:28:39.342000",
            "refNumber": "12355070545"
        }


    ]

}

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

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

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

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	خیر	-	`0`: در انتظار پرداخت `1`: پرداخت موفق و اعلام شده `2`: سفارش لغو شده `3`: پرداخت موفق و اعلام نشده
orderId	String	خیر	-	فیلتر شماره سفارش ارسالی
amount	Long	خیر	-	فیلتر مبلغ

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

{
	"size": 10,
	"page": 1,
	"status": 1,
	"verbose": false
}

بدنه پاسخ

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

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

{
   {
    "total": 1,
    "result": 1,
    "sum": 1000000
    "message": "موفق",
    "data": [
        /* IN CASE verbose == TRUE */

        {
            "description": null,
            "cancelledAt": null,
            "cardNumber": null,
            "refNumber": "12332323223",
            "paidAt": "2019-05-11T18:26:08.545000",
            "status": 1,
            "orderId": "1233456",
            "createdAt": "2019-05-11T15:26:08.545000",
            "amount": 35000,
            "zibalId": 1,
            "multiplexingInfos": [
                {
                    "amount": 21500,
                    "bankAccount": "IR000100000000010988060005",
                    "id": "self"
                },
                {
                    "amount": 10000,
                    "bankAccount": "IR000000000000000010500000",
                    "id": "t0y4M0"
                }
            ]
        }


        /* IN CASE verbose == FALSE */

       {
            "zibalId": 1,
            "refNumber": "12332323223",
            "amount": 35000,
            "paidAt": "2019-04-18T17:43:12.018000",
            "createdAt": "2019-04-18T17:43:12.018000",
            "status": 1,
            "description": null,
            "cancelledAt": null,
            "orderId": "1233456"
        }


    ]

}

ذی‌نفع‌ها

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

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

تعریف ذی‌نفع

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

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

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

بدنه درخواست

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

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

{
    "bankAccount": "IR120620000000246388553648",
    "name": "شرکت راهکار نوین زیبال",
    "callbackUrl": "https://yourapiurl.com/submerchants"
}

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

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

بدنه پاسخ

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

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

{
    "data": {
        "id": "TfZsw2",
        "name": "شرکت راهکارنوین زیبال",
        "bankAccount": "IR120620000000246388553648",
        "status": 1
    },
    "result": 1,
    "message": "موفق"
}

بدنه Callback

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

پارامتر	توضیحات
subMerchant	ذی‌نفع

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

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

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

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

بدنه درخواست

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

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

{
    "subMerchant": {
        "bankAccount": "IR120620000000246388553648"
    }
}

بدنه پاسخ

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

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

{
    "data": [{
        "id": "TfZsw2",
        "name": "شرکت راهکارنوین زیبال",
        "bankAccount": "IR120620000000246388553648",
        "status": 1,
    },{
        "id": "FVm29A",
        "name": "اصغر فرهادی",
        "bankAccount": "IR120620000000442233114455",
        "status": 1
    }],
    "result": 1,
    "total": 2,
    "message": "موفق"
}

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

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

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

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

بدنه درخواست

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

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

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

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

{
    "id": "TfZsw2",
    "name": "زیبال 2",
    "bankAccount": "IR120620000000246388553648"
}

بدنه پاسخ

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

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

{
    "data": {
        "id": "TfZsw2",
        "name": "زیبال 2",
        "bankAccount": "IR120620000000246388553648"
    },
    "result": 1,
    "message": "موفق"
}

اشیاء و مدل‌ها

کیف پول

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

صف تسویه

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

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

تسویه

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

پارامتر	نوع	توضیحات
details	لیستی از جزئیات تسویه	جزئیات هر تسویه (در صورتی که `verbose == true` ارسال می‌شود)
settlementDate	string (ISO-Date)	تاریخ واریز به فرمت ISO-Date
persianSettlementDate	string	تاریخ واریز به فرمت شمسی
refNumber	string	شناسه مرجع
amount	long	مبلغ تسویه (به ریال)
subMerchant	ذی‌نفع	ذی‌نفع تسویه (در صورتی که `verbose == false` تنها `bankAccount` ارسال می‌شود.)

جزئیات تسویه

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

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

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

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

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

ذی‌نفع‌

پارامتر	نوع	توضیحات
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	لیستی از شی آیتم تسهیم	جزئیات تسهیم	بله
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	لیستی از شی آیتم تسهیم	جزئیات تسهیم	بله

آیتم تسهیم

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

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

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

جدول Result

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

result	توضیحات
عمومی
1	موفق
2	API Key به درستی ارسال نشده است.
3	API Key صحیح نیست.
4	اجازه دسترسی به این سرویس صادر نشده‌است.
5	callbackUrl نامعتبر است.
6	یکی از فیلدهای اجباری ارسال نشده‌است. (در message نام فیلد مشخص می‌شود)
7	IP ارسال‌کننده درخواست نامعتبر می‌باشد.
8	API Key غیرفعال است.
9	حداقل مبلغ باید 1000 ریال باشد.
کیف پول
10	کیف پول انتخاب شده وجود ندارد.
11	مبلغ درخواستی از موجودی کیف پول بیشتر است.
12	حداقل مبلغ تسویه 10000 ریال است.
13	تاخیر تسویه از حد مجاز اکانت شما کمتر است.
14	درخواست تسویه مورد نظر وجود ندارد.
15	این مقدار تاخیر تسویه برای حساب کاربری شما مجاز نمی‌باشد.
16	دسترسی این نوع درخواست تسویه برای کیف پول مورد نظر وجود ندارد.
17	امکان ثبت درخواست تسویه آنی برای مبالغ بیشتر از 50 میلیون تومان وجود ندارد.
18	مرچنت درگاه مورد نظر مورد یافت نشد و یا غیر فعال است.
ذی‌نفع
20	نام وارد نشده‌است.
21	شماره شبای وارد شده نامعتبر است (شروع با IR و 26 کاراکتر)
22	ذی‌نفع قبلا ثبت شده است.
23	ذی‌نفع نامعتبر است.
24	ذی‌نفع غیرفعال است.
25	امکان ویرایش ذی‌نفع فعال وجود ندارد.