* ذینفعها
جهت کسب اطلاعات بیشتر درباره ذینفعها این قسمت را مطالعه فرمایید.
به راهنمای سرویس کیف پول زیبال خوش آمدید. این مستندات جهت آسانی استفاده شما از سرویسهای زیبال جمع آوری شدهاند. در صورت بروز هر گونه سوال با تیم فنی زیبال تماس بگیرید. وظیفه همکاران ما پاسخ به پیامهای شما در اسرع وقت میباشد.
لطفا قبل از پیادهسازی به نکات زیر توجه نمایید:
200
و تمامی درخواستهای نامعتبر
400
و خطاهای داخلی سرور زیبال
500
میباشد که در این صورت شما میتوانید با توجه به
message
و
result
و بررسی پارامترهای ارسالی، علت بروز خطا را دریابید.
info@zibal.ir
به سوالات شما در سریعترین زمان ممکن پاسخ خواهد داد.
شما میتوانید به تعداد لازم و از طریق پنل کاربری و دکمه
، کیف پول ایجاد کنید.
همچنین، لیست کیف پولهای شما در پنل کاربری به همراه قابلیت مشاهده گزارشات، درخواست تسویه، تغییر تنظیمات و افزایش موجودی موجود میباشند.
هر کیف پول قابلیت اتصال به درگاه پرداخت اینترنتی زیبال و پلتفرم پرداخت در محل زیبال را دارد.
این مبالغ در سیکلهای پایا به حسابهای مورد نظر شما واریز خواهند شد.
جهت کسب اطلاعات بیشتر درباره ذینفعها این قسمت را مطالعه فرمایید.
همچنین با استفاده از دو دکمهی
میتوانید گزارش تمامی تراکنشهای صورت گرفته بر روی کیف پول خود را مشاهده
نمایید و تنظیمات
مربوط به کیف پول خود (مانند زمان تسویه، نام، حداقل موجودی و ...)
را تغییر دهید.
با توجه به وجود قابلیت تسهیم پویای مبالغ در تمامی سیستمهای پلتفرم پرداختی زیبال
(کیف پول، درگاه پرداخت اینترنتی، دستگاههای کارتخوان)، شما میتوانید از طریق
بخش
به هر تعداد ذینفع تعریف کرده و در پایانههای مربوط به سرویسهای مختلف از آنها
استفاده نمایید.
پس از ثبت درخواست تسویه، بسته به تنظیمات ارسالی شما، این درخواستها در صف تسویه قرار میگیرند تا در موعد مقرر درخواستها به بانک ارسال شده و تسویه صورت بگیرد.
لازم به ذکر است در صورتی که چندین درخواست تسویه برای یک ذینفع ثبت کنید، گزارشات به صورت تجمیعی نمایش داده میشود.
با استفاده از دو دکمه
میتوانید جزئیات تسویه را مشاهده نمایید، یک یا چند درخواست تسویه را حذف نمایید و
یا رسید درخواست را به همراه اطلاعات پیگیری دریافت و چاپ کنید.
پس از موفقیتآمیز بودن تسویهها، اطلاعات درخواست شامل شماره مرجع بانکی که در گزارشات بانکی معتبر میباشد، در جدول گزارشات تسویه قابل مشاهده میباشند.
زیبال از طریق هدر 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 | آرایهای حاوی اطلاعات کیف پولها |
{
"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 | بله | اسم کیف پول |
{
"name": "تستی"
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | wallet | اطلاعات کیفپول |
{
"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 :
برعهده پرداخت کننده
|
{
"id": "10210",
"amount": 10000,
"callbackUrl": "http://localhost:8000/callback.php",
"gatewayMerchant": "test",
"mobile": "09120000000"
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
trackId | Long | شناسه تراکنش |
https://gateway.zibal.ir/start/{trackId}
وارد صفحه درگاه پرداخت می شود. از این مرحله به بعد کلیه مراحل همانند درگاه پرداخت
زیبال خواهد بود. (برای توضیحات بیشتر و استفاده از درگاه مستقیم لطفا به بخش مستند
درگاه پرداخت مراجعه کنید.)
{
"result": 1,
"trackId": 3722194,
"message": "success"
}
{
"result": 1,
"trackId": "5db3fe0c47604a9371647610",
"message": "success"
}
از این پایانه میتوانید جهت استعلام موجودی یک کیف پول استفاده نمایید.
https://api.zibal.ir/v1/wallet/balance
POST
پارامتر | نوع | اجباری؟ | توضیحات |
---|---|---|---|
id | int | بله | شناسه کیف پول |
{
"id": 1010101
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | wallet | اطلاعات و موجودی کیفپول درخواستی |
{
"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 :
برای ارسال لحظه ای درخواست به بانک
پیشفرض: ۱ روز بعد |
uniqueCode | String | خیر | شناسه یکتا به ازای هر تسویه یکتا. این شناسه برای درخواستهای تسویه از یک کیف پول، یکتا است و در صورتی که دو بار یک شناسه در درخواست تسویه ارسال شود، زیبال درخواست دوم را نمیپذیرد. |
bank | String | خیر |
از موجودی کدام بانکِ کیف پول تسویه انجام شود؟
smart :
خودکار (در این حالت ابتدا بانک حساب مقصد که امکان انتقال وجه درون بانکی دارد انتخاب می شود در غیر اینصورت بانکی که بیشترین موجودی را دارد انتخاب می شود.
saman : بانک سامان
ayandeh : بانک آینده
پیشفرض: مقداری که در پنل کاربری قسمت تنظیمات بانک وارد کرده اید. توجه: موجودی کیف پول در هر بانک از پایانه دریافت موجودی قابل دریافت است. |
checkoutDelay
را ارسال نکنید تا
زیبال در نزدیک ترین زمان ممکن تسویه را انجام دهد.
checkoutDelay = -1
ارسال شود همان لحظه درخواست پایا
به بانک مقصد ارسال میشود.
{
"amount": 10000,
"id": 10101,
"bankAccount": "IR060180000000000000020600",
"checkoutDelay": 0,
"description": "تسویه بابت حقوق آقای فرهادی"
}
پارامتر | نوع | توضیحات |
---|---|---|
result | int | نتیجه درخواست |
message | string | پیغام حاوی نتیجه درخواست |
data | جزئیات صف تسویه | میتوانید از
id
ارسالی جهت لغو درخواست استفاده نمایید.
|
{
"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 تسویه که در متد تسویه کیف پول دریافت کردید
|
{
"checkoutQueueId": "5cc976a1ae78bb61149cdc61"
}
پارامتر | نوع | توضیحات |
---|---|---|
result | int | نتیجه درخواست |
message | string | پیغام حاوی نتیجه درخواست |
{
"message": "موفق",
"result": 1
}
از این پایانه میتوانید قبل از انجام تسویه جهت استعلام کارمزد تسویه و چک کردن کافی بودن موجودی تسویه استفاده نمایید.
https://api.zibal.ir/v1/wallet/checkout/wage
POST
پارامتر | نوع | اجباری؟ | توضیحات | |
---|---|---|---|---|
amount | long | بله | مبلغ تسویه (به ریال) | |
id | int | بله | شناسه کیف پول درخواستی جهت تسویه | |
checkoutDelay | int | خیر |
تعداد روزهای تاخیر تسویه (در صورت داشتن دسترسی : 0 :
برای تسویه در همان روز؛ -1 :
برای تسویه لحظهای پایا)
|
{
"amount": 10000,
"id": 10101,
"checkoutDelay": 1,
}
پارامتر | نوع | توضیحات |
---|---|---|
result | int | نتیجه درخواست |
message | string | پیغام حاوی نتیجه درخواست |
data | کارمزد تسویه |
{
"data": {
"wage": 10000,
"sufficient": true
},
"message": "موفق",
"result": 1
}
از این پایانه میتوانید جهت استرداد وجه استفاده کنید.
https://api.zibal.ir/v1/wallet/refund
POST
پارامتر | نوع | اجباری؟ | توضیحات |
---|---|---|---|
trackId | int | بله | شناسه تراکنش موفق درگاه پرداخت زیبال |
amount | int | خیر |
مبلغ مورد نظر به ریال برای ریفاند که باید حتما کوچک تر یا مساوی مبلغ
تراکنش باشد
حداکثر مبلغ ۱۵۰.۰۰۰.۰۰۰ ریال میتواند باشد |
description | string | خیر |
description توضیحات استرداد وجه
|
wageMode | int | خیر |
نحوه کسر کارمزد استرداد وجه کسر از وجه بازگشتی : 1
کسر از کیف پول کارمزد : 2
پیشفرض: کسر از کیف پول کارمزد |
{
"trackId": 196512,
"description": "توضیحات استرداد وجه",
"wageMode": 2
}
پارامتر | نوع | توضیحات |
---|---|---|
refundId | string | شناسه پیگیری ریفاند که بعدا توسط آن میتوانید آخرین اطلاعات و وضعیت ریفاند را استعلام بگیرید |
message | string | پیغام حاوی نتیجه درخواست |
result | int | کد نتیجه درخواست
اگر result==1 باشد درخواست ریفاند موفق ثبت شده است. |
{
"status": true,
"message": "با موفقیت ثبت شد.",
"refundId": "42"
}
گزارش واریزیها
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 | خیر | - | تراکنشهای کیفپول به کیفپول نیز نمایش داده شوند یا خیر |
verbose | boolean | خیر | false |
در صورت true بودن این پارامتر، آرایه
details
ارسال میشود.
|
{
"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 | لیستی از شیء تسویه یا کیفپول به کیفپول | اطلاعات تسویه |
{
"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
ارسال میشود.
|
{
"verbose": false,
"subMerchants": [
{"id": "sjUEMh"},
{"bankAccount":"IR110011001100110011001100"}
]
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | لیستی از شیء صف تسویه | اطلاعات صف تسویه |
{
"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/report/checkout/inquire
POST
پارامتر | نوع | اجباری؟ | مقدار پیشفرض | توضیحات |
---|---|---|---|---|
checkoutRequestId | String | بله | - | شناسه رهگیری تسویه |
{
"checkoutRequestId": "1"
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | وابسته به وضعیت تسویه | پاسخ استعلام تسویه |
وضعیت تسویه (checkoutStatus):
0
موفق
1
برگشت خورده
2
اصلاح به کیفپول
{
"message": "موفق",
"result": 1,
"data": {
"status": "واریز شده",
"type": "checkout",
"checkoutStatus": 0,
"amount": 100000,
"bankAccount": "IRXXXXXXXXXXXXXXX",
"subMerchantName": "همایون شجریان",
"refCode": "XXXXXX",
"trackId": "XXXXXX"
"settlementDate": "2022-03-21T13:45:00.654000",
"settlementDateJalali": "1401/01/01-13:45:00",
"settlementDateJalaliPretty": "01 فروردین 13:45",
"details": [
{
"amount": 100000,
"checkoutWage": 10000,
"checkoutWageMode": 1,
"checkoutRequestId": "1"
}
]
}
}
در این حالت، تسویه در صف تسویه است و تا زمان پردازش سیکل، قابلیت لغو دارد.
{
"message": "موفق",
"result": 1,
"data": {
"status": "در انتظار واریز",
"type": "checkoutQueue",
"amount": 20000,
"subMerchantName": "همایون شجریان",
"checkoutAt": "2022-03-26T15:53:44.232000",
"checkoutAtJalali": "1401/01/06-15:53:44",
"checkoutAtJalaliPretty": "امروز ۱۵:۵۳",
"checkoutWage": 10000,
"checkoutWageMode": 1,
"bankAccount": "IRXXXXXXXXXXXXXXX"
}
}
این تسویه توسط شما لغو شده است.
{
"message": "موفق",
"result": 1,
"data": {
"status": "لغو شده",
"type": "canceledCheckout",
"amount": 20000,
"bankAccount": "IRXXXXXXXXXXXXXXX",
"subMerchantName": "محمد زمان زاده",
"canceledAtJalali": "1401/01/06-15:55:19",
"canceledAtJalaliPretty": "امروز ۱۵:۵۵"
}
}
از این پایانه میتوانید جهت دریافت گزارشات هر درگاه پرداخت استفاده نمایید.
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 | خیر | - |
جستجو بر اساس شماره کارت |
{
"size": 10,
"page": 1,
"merchantId": "5b86d252f92ea1048015ae35",
"verbose": false
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
total | int | تعداد کل نتایج |
sum | Long | جمع کل مبلغ تراکنش ها |
data | لیستی از شیء تراکنش درگاه آنلاین | آرایهای حاوی اطلاعات تراکنشها |
{
{
"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 | خیر | - | فیلتر مبلغ |
{
"size": 10,
"page": 1,
"status": 1,
"verbose": false
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
total | int | تعداد کل نتایج |
sum | Long | جمع کل مبلغ تراکنش ها |
data | لیستی از شیء تراکنش پرداخت در محل | آرایهای حاوی اطلاعات تراکنشها |
{
{
"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/wallet/refund/inquiry
POST
پارامتر | نوع | اجباری؟ | مقدار پیشفرض | توضیحات |
---|---|---|---|---|
refundId | int | بله | - | شناسه استرداد که در پایانه درخواست ریفاند برگشت داده شده است |
{
"refundId": 2859410818,
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
data | شیء استرداد | شیء ای حاوی اطلاعات استرداد |
{
"result": 1,
"data": {
"refundId": "000000000",
"checkoutDetail": {
"type": "",
"amount": 15000,
"subMerchant": {
"bankAccount": "6037900000918673"
},
"refNumber": "220000681",
"settlementDate": "2022-02-18T17:14:02",
"persianSettlementDate": "1400/11/29-17:14:02"
},
"transactionDetail": {
"type": "gateway",
"amount": 15000,
"trackId": 28861100000009210,
"orderId": "1645191598",
"status": 15,
"paidAt": "2022-02-18T17:10:13.152000",
"refNumber": "1944480"
},
"status": 2,
"wage": 10000,
"statusEn": "DONE"
}
}
از این پایانه میتوانید جهت استعلام صاحب حساب مربوط به شماره شبای ارسالی استفاده نمایید.
این سرویس به صورت پیشفرض برای کلیدهای ساختهشده غیرفعال است. لطفا در صورت نیاز به استفاده این سرویس و جهت فعالسازی با ما در تماس باشید.
https://api.zibal.ir/v1/subMerchant/ibanInquiry
POST
پارامتر | ضروری ؟ | نوع | توضیحات |
---|---|---|---|
bankAccount | بله | string | شماره شبا جهت استعلام |
{
"bankAccount": "IR120620000000246388553648",
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | ذینفع | ذینفع اضافهشده (پارامتر name حاوی نام صاحب حساب مورد
استعلام است)
|
{
"data": {
"name": "شرکت راهکارنوین زیبال",
"bankAccount": "IR120620000000246388553648"
},
"result": 1,
"message": "موفق"
}
هر حساب کاربری در زیبال، میتواند بینهایت ذینفع داشته باشد. این ذینفعها در تسهیم به ازای هر سفارش در درگاه پرداخت اینترنتی و پرداخت در محل زیبال و همچنین تسویه مبالغ استفاده میشوند.
با استفاده از پایانهی تعریف ذینفع و یا داخل پنل کاربری زیبال شما میتوانید با ارسال شماره شبای آنها ذینفعهای خود را در سیستم زیبال تعریف کرده و پس از تایید آنها، درخواست تسویه برای آن حسابها صادر نمایید.
از این پایانه جهت تعریف ذینفع و ثبت آن در سیستم زیبال جهت استفاده در سفارشهای دارای تسهیم استفاده کنید.
https://api.zibal.ir/v1/subMerchant/create
POST
پارامتر | ضروری ؟ | نوع | توضیحات |
---|---|---|---|
bankAccount | بله | string | شماره شبای ذینفع در حال تعریف |
name | بله | رشته (String) | نام ذینفع (شماره شبای ارسالی میبایست به این نام باشد. در غیر اینصورت ذینفع غیرفعال خواهد ماند.) |
callbackUrl | خیر | رشته (String) | آدرسی که زیبال تغییر وضعیت این ذینفع را به آن ارسال میکند. (بدنه callback) |
{
"bankAccount": "IR120620000000246388553648",
"name": "شرکت راهکار نوین زیبال",
"callbackUrl": "https://yourapiurl.com/submerchants"
}
پس از فراخوانی موفقیتآمیز این پایانه، وضعیت ذینفعها به در حال بررسی
تغییر میکنند. کارشناسان زیبال با بررسی اطلاعات وارد شده نسبت به تایید /
رد کردن ذینفعهای ثبتشده در ساعات کاری در کسری از ثانیه و در باقی
زمانها تا 8 ساعت اقدام میکنند. این وضعیتها در
پنل کاربری شما قابل مشاهده خواهد بود و همچنین از طریق متد
POST
به آدرس
callbackUrl
اعلامی ارسال میشوند.
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
subMerchant | ذینفع | ذینفع اضافهشده |
{
"data": {
"id": "TfZsw2",
"name": "شرکت راهکارنوین زیبال",
"bankAccount": "IR120620000000246388553648",
"status": 1
},
"result": 1,
"message": "موفق"
}
در صورتی که در بدنهی پایانهی
تعریف ذینفع
callbackUrl
صحیح وارد کرده باشید، زیبال تغییر وضعیت ذینفع را از طریق ارسال اطلاعات به آن
آدرس به اطلاع شما میرساند.
پارامتر | توضیحات |
---|---|
subMerchant | ذینفع |
از این پایانه جهت مشاهده لیست ذینفعهای ثبتشده استفاده نمایید.
https://api.zibal.ir/v1/subMerchant/list
POST
پارامتر | ضروری ؟ | نوع | توضیحات |
---|---|---|---|
subMerchant | خیر | فیلتر ذینفعها | لیست ذینفعها بر اساس این مقدار فیلتر میشوند |
page | int | خیر | شماره صفحه (از 1 شروع میشود) |
size | int | خیر | تعداد گزارشات در هر صفحه |
{
"subMerchant": {
"bankAccount": "IR120620000000246388553648"
}
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | لیستی از ذینفع | لیست ذینفعهای اضافهشده |
total | int | تعداد کل نتایج |
{
"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 | بله | رشته (String) | شماره شبای ویرایش شده |
name | بله | رشته (String) | نام ویرایش شده |
این پایانه تنها جهت ویرایش
ذینفعهای غیرفعال
استفاده میشود.
ارسال حداقل یکی از دو پارامتر
name
و
bankAccount
جهت تغییر اجباری میباشد.
{
"id": "TfZsw2",
"name": "زیبال 2",
"bankAccount": "IR120620000000246388553648"
}
پارامتر | نوع | توضیحات |
---|---|---|
message | string | پیغام حاوی نتیجه درخواست |
result | int | نتیجه درخواست (جدول Resultها) |
data | ذینفع | ذینفع ویرایششده |
{
"data": {
"id": "TfZsw2",
"name": "زیبال 2",
"bankAccount": "IR120620000000246388553648"
},
"result": 1,
"message": "موفق"
}
پارامتر | نوع | توضیحات |
---|---|---|
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 | توضیحات |
هر آیتم صف تسویه متشکل از یک یا چند درخواست تسویه میباشد که این درخواستها در قالب
این شیء و در آرایهی
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 | شماره آیدی کیف پول |
*حداقل یکی از دو مقادیر آیدی کیف پول یا شماره شبا الزامی است
این شیء اطلاعات استرداد را نشان میدهد.
پارامتر | نوع | توضیحات |
---|---|---|
refundId | String | شناسه استرداد |
checkoutDetail | شیء واریز | شیء ای حاوی اطلاعات واریز |
transactionDetail | شیء تراکنش درگاه | شیء ای حاوی اطلاعات تراکنش درگاه |
statusEn | String | وضعیت درخواست استرداد
PENDING :
در انتظار پردازش
ALLOCATED :
پردازش شده در انتظار واریز
DONE :
پایانه یافته
|
status | int | وضعیت درخواست استرداد
0 :
در انتظار پردازش
1 :
پردازش شده در انتظار واریز
2 :
پایانه یافته
|
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 | امکان ثبت درخواست تسویه آنی برای مبالغ بیشتر از 100 میلیون تومان وجود ندارد. |
18 | مرچنت درگاه مورد نظر مورد یافت نشد و یا غیر فعال است. |
ذینفع | |
20 | نام وارد نشدهاست. |
21 | شماره شبای وارد شده نامعتبر است (شروع با IR و 26 کاراکتر) |
22 | ذینفع قبلا ثبت شده است. |
23 | ذینفع نامعتبر است. |
24 | ذینفع غیرفعال است. |
25 | امکان ویرایش ذینفع فعال وجود ندارد. |
26 | مقدار اعتبار استعلام شبای شما به پایان رسیده است. |
استرداد | |
50 | تراکنشی یافت نشد. |
51 | کیف پول مورد نظر یافت نشد. |
52 | ریفاند این تراکنش در حال پردازش است. |
53 | ریفاند این تراکنش انجام شده است. |
54 | تراکنش درخواست شده موفق نبوده است. |
55 | مبلغ وارد شده از مبلغ تراکنش بیشتر است. |
56 | امکان ریفاند این تراکنش به دلیل عدم دسترسی به شماره کارت میسر نیست. |
57 | شماره کارت معتبر نیست. |
58 | موجودی کیف پول شما برای انجام این ریفاند کافی نیست. |
59 | مبلغ ریفاند از 1000 تومان کمتر است. |
60 | موجودی کیف پول شما برای کسر کارمزد این ریفاند کافی نیست. |
61 | مقدار refund باید از 15 میلیون تومان کمتر باشد. |