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

نسخه آزمایشی
آخرین به روز رسانی :‌ 21 مهر 1399

مقدمه

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

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

  • سرویس‌های پیش‌رو سرویس‌های آزمایشی هستند و کارشناسان فنی زیبال مشتاق اعمال نظرات و پیشنهادات شما در سرویس نهایی هستند!
  • تمامی درخواست‌های شما از طریق بخش قابل مشاهده هستند.
  • 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 را ارسال نکنید تا زیبال در نزدیک ترین زمان ممکن تسویه را انجام دهد.
  • در کیف پول پرداختیاری حداکثر امکان تسویه با 8 شماره شبا در یک روزکاری امکان پذیر است.
  • در صورتیکه checkoutDelay = 0 را ارسال کنید موجودی قابل برداشت شما در صورتی که قبل از ساعت 13 درخواست دهید همان روز در سیکل بعد از ظهر پایا تسویه می‌شود.
  • در صورتیکه 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/wallet/refund POST
بدنه درخواست
پارامتر نوع اجباری؟ توضیحات
trackId int بله trackId شماره تراکنشی که پس از انجام تراکنش انجام شده است
description string خیر description توضیحات استرداد وجه

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


{
	"trackId": 124578963,
	"description": "استرداد"
}
بدنه پاسخ
پارامتر نوع توضیحات
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 امکان ویرایش ذی‌نفع فعال وجود ندارد.