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

آخرین به روز رسانی :‌ 01 بهمن 1397

مقدمه

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

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

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

احراز هویت

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

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

تمامی درخواست‌های ارسالی به زیبال بایستی حاوی اطلاعات احراز هویت باشند :
{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    // OTHER FIELDS
}

سفارش (Order)

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

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

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

تسهیم

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

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

تسهیم

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

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

{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    "orderId": "25",
    "callbackUrl": "http://yourapiurl.com/callback.php",
    "amount": 150000,
    "percentMode": 0,
    "description": "Hello World!",
    "multiplexingInfos": [
        {
          "id": "self",
          "amount": 100000
        },
        {
          "id": "QEsxEq",
          "amount": 50000
        }
      ]
}
بدنه پاسخ
پارامتر توضیحات
zibalId در صورت موفقیت‌آمیز بودن ثبت سفارش، این عدد به عنوان شناسه زیبال در پاسخ برگردانده می‌شود. این شناسه راه ارتباطی دستگاه‌های کارت‌خوان با سفارشات ثبت شده‌ی شما در سیستم زیبال است. با ورود این شناسه و یا اسکن بارکد مربوط به این شناسه اطلاعات پرداخت سفارش بر روی دستگاه کارت‌خوان نمایان خواهد شد. جهت دریافت بارکُد مربوط به این شناسه به قسمت بارکد در این سند مراجعه نمایید.
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
{
    "zibalId": 727,
    "zibalFee": 10000,
    "result": 1,
    "message" : "success"
}
جدول result
کد توضیحات
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
3 orderId معتبر نمی‌باشد.
4 سفارشی با این orderId قبلا در زیبال ثبت‌شده‌است.
5 percentMode نامعتبر می‌باشد. (تنها 0 و 1 قابل قبول هستند)
6 amount بایستی بزرگتر از 10,000 ریال باشد.
7 یک یا چند ذی‌نفع در multiplexingInfos نامعتبر می‌باشند. اطلاعات بیشتر
8 یک یا چند ذی‌نفع در multiplexingInfos غیرفعال می‌باشند. اطلاعات بیشتر
9 id = self در multiplexingInfos وجود ندارد.
10 amount با مجموع سهم‌ها در multiplexingInfos برابر نمی‌باشد.
11 callbackUrl نامعتبر می‌باشد. (شروع با http و یا https)
18 موجودی کیف‌پول اصلی شما جهت ثبت این سفارش کافی نمی‌باشد. (در صورتی که feeMode == 1 )

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

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

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

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

اطلاعات درخواست
https://sandbox-api.zibal.ir/merchant/readOrder POST
بدنه درخواست
پارامتر ضروری ؟ نوع توضیحات
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId یا zibalId رشته (String) شناسه سفارشی که قصد دریافت اطلاعات آن را دارید.
zibalId یا orderId رشته (String) شناسه زیبال سفارشی که قصد دریافت اطلاعات آن را دارید.
{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    "orderId": "25"
}
بدنه پاسخ
پارامتر توضیحات
zibalId شناسه زیبال این سفارش
orderId شناسه سفارش
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
status وضعیت سفارش. مشاهده جزئیات در جدول وضعیت سفارش‌ها
refNumber (در صورتی که سفارش پرداخت‌شده باشد) - شماره مرجع پرداخت
createdAt تاریخ ثبت سفارش (به فرمت ISO-Date)
paidAt (در صورتی که سفارش پرداخت‌شده باشد) - تاریخ پرداخت (به فرمت ISO-Date)
canceledAt (در صورتی که سفارش لغو ‌شده باشد) - تاریخ لغو (به فرمت ISO-Date)
multiplexingInfos اطلاعات تسهیم سفارش. در این آرایه شماره شبای هر ذی‌نفع و سهم هر کدام از سفارش وجود دارند.
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست

شماره شبا

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

Order Id - Zibal Id

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

{
    "orderId": "250",
    "result": 1,
    "refNumber": null,
    "createdAt": "2017-01-25T23:43:01.053000",
    "paidAt": "2017-02-27T09:24:31.053000",
    "amount": 150000,
    "zibalFee": 10000,
    "status": 1,
    "zibalId": 17,
    "description": "Hello World!",
    "canceledAt": null,
    "message": "success",
    "multiplexingInfos": [
      {
        "bankAccount": "IR120620000000322394250009",
        "amount": 100000
      },
      {
        "bankAccount": "IR120620000000202374130392",
        "amount": 50000
      }
    ],
}
جدول Status Code
status وضعیت
0 در انتظار پرداخت
1 پرداخت‌شده
2 لغو شده
جدول result
کد توضیحات
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
12 یکی از پارامترهای orderId و zibalId بایستی ارسال شوند.

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

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

لغو سفارش

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

لغو سفارش

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

اطلاعات درخواست
https://sandbox-api.zibal.ir/merchant/cancelOrder POST
بدنه درخواست
پارامتر ضروری ؟ نوع توضیحات
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
orderId یا zibalId رشته (String) شناسه سفارشی که قصد لغو کردن آن را دارید.
zibalId یا orderId رشته (String) شناسه زیبال سفارشی که قصد لغو کردن آن را دارید.
{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    "orderId": "25"
}

Order Id - Zibal Id

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

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

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

ویرایش سفارش

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

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

ویرایش سفارش

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

{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    "orderId": "25", //YOU SHOULD HAVE ADDED AN ORDER WITH THIS ORDERID
    "callbackUrl": "http://yourapiurl.com/callback.php",
    "amount": 2150000,
    "percentMode": 0,
    "description": "Hello World!",
    "multiplexingInfos": [
        {
          "id": "self",
          "amount": 2100000
        },
        {
          "id": "QEsxEq",
          "amount": 50000
        }
      ]
}
بدنه پاسخ
پارامتر توضیحات
zibalId شناسه زیبال سفارش ویرایش شده.
zibalFee کارمزد زیبال محاسبه شده بر اساس اطلاعات سفارش (به ریال)
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
{
    "zibalId": 727,
    "zibalFee": 10000,
    "result": 1,
    "message" : "success"
}
جدول result
کد توضیحات
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
3 سفارشی با orderId ارسالی شما در سیستم زیبال موجود نمی‌باشد.
5 percentMode نامعتبر می‌باشد. (تنها 0 و 1 قابل قبول هستند)
6 amount بایستی بزرگتر از 10,000 ریال باشد.
7 یک یا چند ذی‌نفع در multiplexingInfos نامعتبر می‌باشند. اطلاعات بیشتر
8 یک یا چند ذی‌نفع در multiplexingInfos غیرفعال می‌باشند. اطلاعات بیشتر
9 id = self در multiplexingInfos وجود ندارد.
10 amount با مجموع سهم‌ها در multiplexingInfos برابر نمی‌باشد.
11 callbackUrl نامعتبر می‌باشد. (شروع با http و یا https)
18 موجودی کیف‌پول اصلی شما جهت ثبت این سفارش کافی نمی‌باشد. (در صورتی که feeMode == 1 )

ذی‌نفع‌ها

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

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

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

id = self

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

تعریف ذی‌نفع

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

اطلاعات درخواست
https://sandbox-api.zibal.ir/merchant/addSubMerchant POST
بدنه درخواست
پارامتر ضروری ؟ نوع توضیحات
merchantId بله رشته (String) ضروری جهت احراز هویت
secretKey بله رشته (String) ضروری جهت احراز هویت
bankAccount بله رشته (String) شماره شبای ذی‌نفع در حال تعریف
name بله رشته (String) نام ذی‌نفع (شماره شبای ارسالی می‌بایست به این نام باشد. در غیر این‌صورت ذی‌نفع در حال تعریف غیرفعال خواهد ماند.)
callbackUrl خیر رشته (String) آدرسی که زیبال فعال/غیرفعال شدن این ذی‌نفع را به آن ارسال می‌کند.
{
    "merchantId": "Your Merchant ID",
    "secretKey": "Your Secret Key",
    "bankAccount": "IR120620000000246388553648",
    "name": "zibal"
}

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

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

بدنه پاسخ
پارامتر توضیحات
id شناسه‌ای که با ارسال آن به‌عنوان id در multiplexingInfos می‌توانید دستور تسهیم را برای این ذی‌نفع صادر نمایید.‌
result نتیجه درخواست. اطلاعات بیشتر درباره این عدد در جدول Result Code زیر آمده‌است.
message پیغام انگلیسی حاوی نتیجه درخواست
{
    "id": "SZweQz",
    "result": 1,
    "message": "success"
}
جدول result
کد توضیحات
1 با موفقیت انجام شد.
2 احراز هویت با خطا همراه بود.
11 callbackUrl نامعتبر می‌باشد. (شروع با http و یا https)
14 name نامعتبر می‌باشد.
15 bankAccount نامعتبر می‌باشد. (شماره شبا حاوی 26 کاراکتر می‌باشد و با IR شروع می‌شود.)
16 bankAccount قبلا در بین ذی‌نفع‌های شما تعریف شده است. (در این صورت id ذی‌نفع قبلی در پاسخ ارسال می‌گردد)
بدنه Callback

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

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

Callback

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

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

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

بارکد

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

اطلاعات درخواست
https://api.zibal.ir/merchant/generateBarcode?zibalId={{zibalId}} GET

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

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

مثال

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

نمونه‌کدها

پرستاشاپ - تا نسخه 1.6 دانلود / راهنما


ASP.NET راهنما


ووکامرس دانلود / راهنما


گرویتی‌فرم دانلود / راهنما