آخرین تغییرات: ۱۴۰۰/۰۴/۰۸

مقدمه

دایرکت دبیت یا سرویس اشتراک چیست:

سرویس اشتراک یا دایرکت دبیت سرویسی است که یک فرد وجوهی را از حساب بانکی شخص دیگری خارج میکند در واقع شما به بانک اجازه میدهید که مبلغی را مستقیما از حسابتان کسر و در قبال آن خدماتی را به شما ارایه دهد. به طور کلی دایرت دبیت برداشت مستقیم پول برای انجام معاملات مالی در صورت صدور مجوز توسط پرداخت کننده می باشد. این کار بیشتر زمانی انجام می شود که شما بخواهید اشتراک خود را تمدید کنید. شما می توانید در وندار به وسیله این API اشتراک حساب های خود را مدیریت کنید. تمامی API های وندار بر اساس معماری REST پیاده سازی شده و آدرس آن به شرح زیر می باشد:

برای تمامی درخواست های ارسالی باید مقادیر زیر در هدر ارسال شوند: توکن همان کلید API یی است که از وندار دریافت کرده اید.

Accept: application/json
Authorization Bearer {Token}
                        

سرویس دریافت توکن (AUTHORIZATION)

۱. ایجاد درخواست اشتراک:

اولین مرحله برای دریافت دسترسی به حساب بانکی و ایجاد یک اشتراک جدید،ثبت درخواست اشتراک است. لازم است که درخواست اشتراک خود را به آدرس زیر ارسال کنید.

Method: POST
Address: https://api.vandar.io/v2/business/{business}/subscription/authorization/store
                        

پارامترهای مجاز

name Type Status
bank_code string required
mobile string required
callback_url string required
count integer required
limit integer required
name string optional
email string optional
expiration_date date optional
wage_type string optional

توضیحات

  • bank_code (اجباری): کد بانک که از جدول زیر قابل دسترسی است.
    نکته! اگر چه داکیومنت ما همواره به روز می‌شود اما معیار اصلی بر اساس وضعیت سلامت بانک‌ها است.
    پارامتر has_direct_debit_ability: نشان‌دهنده‌ی این است که بانک مربوطه دارای قابلیت دایرکت‌دبیت (سرویس اشتراک) هست یا خیر.
    پارامتر is_healthy_on_direct_debit: نشان‌دهنده‌ی این است که در آن لحظه‌ی خاص با توجه به وضعیت سلامت بانک مورد نظر، امکان ریدایرکت به صفحه‌ی بانک وجود دارد یا خیر.

    Bank Code Current Health

  • mobile (اجباری): شماره موبایل کاربر. شماره موبایل بدون کد کشور و به فرمت 09123456789 باشد.
  • نکته! دقت داشته باشید که در صورت منتقل شدن به صفحه‌ی بانک با این شماره موبایل، برای بانک‌هایی که برای ورود نیاز به کد ملی کاربر دارند، بایستی کد ملی و شماره موبایل متعلق به یک شخص باشند. در غیر این صورت در صفحه‌ی بانک با پیغام خطا روبرو می‌شود و امکان ورود پیدا نمی‌کند.

  • callback_url (اجباری): باید با آدرس درگاه پرداخت تایید شده در وندار بر روی یک دامنه باشد
  • count (اجباری): حداکثر تعداد دفعاتی که در یک ماه می‌توان با این مجوز، برداشت وجه موفق انجام داد.
  • limit (اجباری): حداکثر مبلغ قابل برداشت وجه در برداشت وجه‌های مربوط به این مجوز. واحد پول ریال است.
  • name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
  • email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.
  • expiration_date (اختیاری): تاریخ انقضای اشتراک. این تاریخ می‌تواند تاریخ امروز یا بعد از آن باشد و به صورت میلادی وارد می‌شود. در صورتی که ارسال نشود، تاریخ سه سال بعد در نظر گرفته می‌شود.
  • wage_type (اختیاری): میزان کارمزد ، که میتواند دو مقدار APPLICATION_USER یا APPLICATION_SELF باشد اگر این مقدار را برابر با APPLICATION_SELF قرار دهید میزان کارمزد از شما کسر میشود و اگر برابر با APPLICATION_USER قرار دهید این مقدار از کاربر کسر میشود .
  • نکته! اگر مقدار wage_type در درخواست ارسال نشود این مقدار از بخش اشتراک -> جزییات که در پنل کاربری شما در وندار قرار گرفته است خوانده می شود.
    نکته! در صورتی که wage_type در پنل کاربری شما APPLICATION_SELF و در درخواست ارسالی شما APPLICATION_USER باشد و یا برعکس ، اولویت با درخواستی است که ارسال کرده اید.

نمونه json

{
  "bank_code": "062",
  "mobile": "09123456789",
  "callback_url": "https://paperpiano.ir/subscription/callback",
  "count": 7,
  "limit": 10000,
  "name": "محمد مقصودی",
  "wage_type":"APPLICATION_USER",
  "email": "yourcustomer@gmail.com",
  "expiration_date": "2021-03-03"
}
                        

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "status": 1,
  "message": "درخواست توکن با موفقیت ثبت شد.",
  "result": {
    "authorization": {
      "token": "0cf235d0-d48b-11ea-86cd-298ec898a9bd"
    }
  }
}
                        
نکته! token دریافتی در این قسمت یکبار مصرف است و پس از ۲۰ دقیقه باطل می شود.
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام درخواست توکن با موفقیت ثبت شد.
  • result:
    • authorization:
      • token: آیدی شما در سرویس اشتراک که باید درخواست های بعدی خود را با این آیدی ارسال کنید.

نمونه پاسخ دریافتی نا موفق:

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}
                        
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

۲. انتقال کاربر به صفحه بانک

در مرحله بعد token دریافتی از قسمت قبل را در انتهای آدرس می گذارید و در مرورگر وارد سایت می شوید.

METHOD: get
URL: https://subscription.vandar.io/authorizations/{token}
                      

در صورتی که در ارتباط با بانک اختلال پیش آمده باشد شما با آدرس زیر روبرو می‌شوید:

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&status=FAILED_TO_ACCESS_BANK
  • token: توکنی که با استفاده از آن تلاش کرده‌اید تا به صفحه‌ی بانک منتقل شوید.

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

صفحه ورود بانک

با وارد کردن کد ملی و گذر واژه صحیح وارد صفحه زیر می شوید.

صفحه دسترسی

۳. دریافت کد اشتراک

در صورتی که کاربر بر روی دکمه دسترسی دارد کلیک کند، وندار کاربر را به آدرس برگشتی که در مرحله اول ارسال کرده‌اید به همراه پارامتر token و status و authorization_id هدایت می‌کند.

در صورت اجازه‌ی دسترسی به حساب در صفحه‌ی بانک

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&authorization_id=9f307e30-dc77-11ea-830e-7533ca1787c5&status=SUCCEED

در صورت عدم اجازه‌ی دسترسی به حساب در صفحه‌ی بانک

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&status=FAILED&error_code=21
  • token: توکنی که با استفاده از آن تلاش کرده‌اید تا به صفحه‌ی بانک منتقل شوید.
  • error_code: کد خطایی که به دلیل آن این درخواست ناموفق بوده است که می توانید با استفاده از جدول زیر توضیحات هر کد را ببینید.
description error_code
خطای غیرمنتظره 00
وضعیت واگذاری در حالت ایجاد شده نمیباشد 01
کاربر بعد از ورود به بانک، در صفحه قرارداد روی دکمه بازگشت کلیک کرده است 02
خطا در دریافت توکن بانک رخ داده است. 03
خطای سرور 04
خطای نامشخص 05
کد ملی که برای صاحب شماره موبایل در پیمان ثبت شده است، با کد ملی لاگین کننده در بانک مغایرت دارد 06
ذخیره مشخصات مشتری با خطا مواجه شده است 07
شماره حساب فعالی برای این کاربر یافت نشد 08
دریافت اطلاعات حساب مشتری با خطا مواجه شده است 09
شناسه موسسه مورد نظر یافت نشد/نامعتبر است 10
تاریخ ورودی برای این قرارداد نامعتبر است 11
شماره پیگیری مورد نظر یافت نشد/نامعتبر است 12
وضعیت موسسه نامعتبر است 13
مقدار نادرست برای مقادیر ثابت 14
بانک مورد نظر یافت نشد 15
وضعیت بانک نامعتبر است 16
کاربر مجاز به انجام عملیات نیست 17
سپرده متعلق به کاربر نیست/عدم امکان دسترسی به سپرده/عدم وجود حق برداشت/برداشت امکانپذیر نیست 18
شماره سپرده مورد نظر وجود ندارد 19
خطای عدم دسترسی 20
خطای داخلی بوم 21
بانک درخواست شده در لیست بانک های دردسترس وندار نیست 22
اپلیکیشن مربوط به درخواست شما موجود نیست 23
اپلیکیشن مربوط به درخواست شما فعال نیست 24
پاسخ مناسب از سمت بانک دریافت نشد 25
خطای غیر منتظره‌ای در بستن قرارداد رخ داده است 26
کاربر، در صفحه قرارداد روی دکمه بازگشت کلیک کرده است 27
سرویس همراه کارت پاسخ مناسب ارسال نکرده است 28
صفحه مجوز منقضی شده است 29

۴. لیست اشتراک‌ها

در این بخش شما می توانید لیست اشتراک های ایجاد شده را مشاهده کنید.

METHOD: GET
URL: https://api.vandar.io/v2/business/{business}/subscription/authorization

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد مشاهده‌ی اشتراک‌های آن را دارید.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "data": [
    {
      "id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
      "customer_uuid": "b4d1e440-d426-11ea-a9d3-051cbf7b8f81",
      "token": "96ff2c90-d426-11ea-b499-6ddbc3441df4",
      "bank_code": "062",
      "callback_url": "http:\/\/vandar.ui\/dd\/callback.php",
      "count": 7,
      "limit": "10200",
      "mobile": "09129311989",
      "name": "محمد مقصودی",
      "email": "customer.email@gmail.com",
      "national_code": "2993968416",
      "expiration_date": "1400\/04\/04 14:47:09",
      "created_at": "1399\/04\/04 14:47:09"
    },
    ...
  ],
  "links": {
    "first": "https://api.vandar.io/v2/business/vandario/subscription/authorization?page=1",
    "last": "https://api.vandar.io/v2/business/vandario/subscription/authorization?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.vandar.io/v2/business/vandario/subscription/authorization",
    "per_page": 20,
    "to": 3,
    "total": 3
  }
}
  • data:
    • id: آیدی اشتراک که برای درخواست برداشت وجه از این آیدی استفاده می شود.
    • customer_uuid: شناسه مشتری کسب و کار شما
    • token: توکنی که در مرحله اول برای شما ارسال شده است.
    • bank_code: کد بانک که لیست آن در بالا اشاره شده است.
    • callback_url: آدرس بازگشتی ای که در زمان درخواست ارسال کرده اید.
    • count: رشته عددی مشخص کننده تعداد درخواست های برداشت وجه که به صورت ماهیانه مشخص می‌شود.
    • limit: رشته عددی مشخص کننده حداکثر مبلغ برداشت وجه در هر برداشت. واحد پول ریال است.
    • mobile: شماره موبایل کاربر
    • name: نام کاربر اگر در مرحله قبل ارسال کردید
    • email: ایمیل کاربر اگر در مرحله قبل ارسال کردید
    • national_code: کدملی کاربر در صورتی که بانک به وندار برگردانده باشد
    • expiration_date (اختیاری): تاریخ انقضای اشتراک. این تاریخ می‌تواند تاریخ امروز یا بعد از آن باشد و به صورت میلادی وارد می‌شود. در صورتی که ارسال نشود، تاریخ سه سال بعد در نظر گرفته می‌شود.
    • created_at: زمان ساخت اشتراک
  • links:
    • first: آدرس اولین صفحه
    • last: آدرس آخرین صفحه
    • prev: آدرس صفحه قبل
    • next: آدرس صفحه بعد
  • meta:
    • current_page: آدرس همین صفحه
    • from: شماره اولین آیتم که در این صفحه آمده است
    • last_page: تعداد کل صفحات
    • path: آدرس خالص بدون صفحه بندی
    • per_page: تعداد آیتم در هر صفحه
    • to: شماره آخرین آیتمی که در این صفحه آمده است
    • total: تعداد کل آیتم ها
نکته! در این قسمت در خروجی id را دریافت میکنیم که مطابق با همان subscription_code دریافتی از url در مرحله قبل می باشد. و در مراحل بعد برای استفاده از متد show و revoke که برای نمایش و پاک کردن اشتراک است مورد استفاده قرار میگیرد.

نمونه پاسخ دریافتی نا موفق:

HTTP/1.1 401
{
"status": 0,
"error": "Unauthenticated"
}
  
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

۵. نمایش یک اشتراک با id

شما می توانید با این دستور جزییات یک اشتراک را با فرستادن id دریافت کنید.

Method: GET
Address: https://api.vandar.io/v2/business/{business}/subscription/authorization/{id}

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد مشاهده یکی از اشتراک های آن را دارید.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "status": 1,
  "message": "مجوز با موفقیت به نمایش در آمد.",
  "result": {
    "authorizations": {
      "id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
      "customer_uuid": "b4d1e440-d426-11ea-a9d3-051cbf7b8f81",
      "token": "96ff2c90-d426-11ea-b499-6ddbc3441df4",
      "bank_code": "062",
      "callback_url": "http:\/\/vandar.ui\/dd\/callback.php",
      "count": 7,
      "limit": "10200",
      "mobile": "09129311989",
      "name": "محمد مقصودی",
      "email": "customer.email@gmail.com",
      "national_code": "2993968416",
      "expiration_date": "1400\/04\/04 14:47:09",
      "created_at": "1399\/04\/04 14:47:09"
    }
  }
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام مجوز با موفقیت به نمایش در آمد
  • result:
    • authorizations:
      • id: آیدی اشتراک که برای درخواست برداشت وجه از این آیدی استفاده می شود.
      • customer_uuid: شناسه مشتری کسب و کار شما
      • token: توکنی که در مرحله اول برای شما ارسال شده است.
      • bank_code: کد بانک که لیست آن در بالا اشاره شده است.
      • callback_url: آدرس بازگشتی ای که در زمان درخواست ارسال کرده اید.
      • count: رشته عددی مشخص کننده تعداد درخواست های برداشت وجه که به صورت ماهیانه مشخص می‌شود.
      • limit: رشته عددی مشخص کننده حداکثر مبلغ برداشت وجه در هر برداشت. واحد پول ریال است.
      • mobile: شماره موبایل کاربر
      • name: نام کاربر اگر در مرحله قبل ارسال کردید
      • email: ایمیل کاربر اگر در مرحله قبل ارسال کردید
      • national_code: کدملی کاربر در صورتی که بانک به وندار برگردانده باشد
      • expiration_date (اختیاری): تاریخ انقضای اشتراک. این تاریخ می‌تواند تاریخ امروز یا بعد از آن باشد و به صورت میلادی وارد می‌شود. در صورتی که ارسال نشود، تاریخ سه سال بعد در نظر گرفته می‌شود.
      • created_at: زمان ساخت اشتراک

نمونه پاسخ دریافتی ناموفق:

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

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}

در صورتی که برنامه ای مربوط به نام کسب و کار ارسال شده در آدرس، وجود نداشت پاسخ زیر را دریافت می کنید:

HTTP/1.1 404
{
  "status": 0,
  "message": "برنامه کاربردی با این شناسه کاربری یافت نشد"
}

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

HTTP/1.1 404
{
  "status": 0,
  "message": "چنین مجوزی یافت نشد."
}

اگر مجوز مربوط به آیدی ارسال شده باطل شده باشد، خطای زیر را دریافت می کنید:

HTTP/1.1 422
{
  "message": "The given data was invalid.",
  "errors": {
      "message": [
          "مجوز باطل شده است."
      ]
  }
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: آرایه ای از خطا‌ها

۶. پاک کردن یک اشتراک با استفاده از id

Method: DELETE
Address: https://api.vandar.io/v2/business/{business}/subscription/authorization/{id}

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد حذف یکی از اشتراک های آن را دارید.

پارامتر {id} همان id مربوط به اشتراکی است که قصد حذف آن را دارید.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "status": 1,
  "message": "مجوز با موفقیت لغو گردید.",
  "result": {
    "authorizations": {
      "id": "9f307e30-dc77-11ea-830e-7533ca1787c5"
    }
  }
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام مجوز با موفقیت لغو گردید
  • result:
    • authorization:
      • id: آیدی اشتراک حذف شده

نمونه پاسخ دریافتی ناموفق:

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

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

در صورتی که اشتراکی با id ارسال شده موجود نباشد پاسخ زیر را دریافت می کنید:

HTTP/1.1 404
{
  "status": 0,
  "message": "خطای ۴۰۴ رخ داده است"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: آرایه ای از خطا‌ها

سرویس برداشت وجه (Withdrawal)

سرویس برداشت وجه از حساب دیگران، این سرویس هنگامی به کار می‌رود که شما قصد دارید از حساب مشتریان خود یکبار یا به صورت دوره‌ای وجهی را برداشت کنید.

۱. ثبت درخواست برداشت وجه

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

Method: POST
Address: https://api.vandar.io/v2/business/{business}/subscription/withdrawal/store

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد برداشت وجه از اشتراک آن را دارید.

پارامترهای مجاز

name Type Status
authorization_id string required
amount numeric required
withdrawal_date string required if is_instant=0
is_instant Integer (0,1) optional
notify_url string optional
max_retry_count integer optional
description string optional

توضیحات

دو نوع برداشت امکان پذیر است. در همین لحظه (is_instant=1) و برداشت در آینده (is_instant=0):

در صورت برداشت آنی (is_instant=1) برداشت از حساب کاربر در همان لحظه انجام می شود. در این حالت ۲ پارامتر withdrawal_date و max_retry_count از درخواست شما محاسبه نمی شوند بلکه withdrawal_date همیشه برابر تاریخ امروز و max_retry_count همیشه برابر با ۱ در نظر گرفته می شوند. بودن یا نبودن این دو پارامتر در درخواست شما تغییری ایجاد نمی کند.

در صورت برداشت در آینده (is_instant=0) برداشت از حساب کاربر زمانی در آینده رخ خواهد داد. این زمان را شما با پارامتر withdrawal_date تعیین می کنید و در حالت برداشت در آینده این پارامتر اجباری است و باید تاریخ صحیحی بعد از امروز باشد. در این حالت پارامتر max_retry_count اختیاری است و در صورت وجود نداشتن در درخواست شما برابر با ۱ در نظر گرفته می شود. اما اگر عدد دیگری برای max_retry_count تعیین کنید، عدد در خواست شما برای این پارامتر منظور می شود.

  • authorization_id (اجباری): آیدی دریافتی در بخش اشتراک که می خواهید مبلغ از آن دسترسی برداشت شود
  • amount (اجباری): مبلغ برداشت وجه
  • withdrawal_date (اجباری در حالت is_instant=0): تاریخی که در آن روز از حساب برداشت شود. روز معین شده باید بعد از امروز باشد.
  • is_instant (اختیاری): این پارامتر مشخص می‌کند که برداشت وجه در همین لحظه انجام شود یا در آینده. مقدار این پارامتر می تواند 0 یا 1 باشد. 1 به معنای این که برداشت در لحظه انجام شود و 0 به این معنا که برداشت در آینده انجام شود. در صورت عدم ارسال، 1 در نظر گرفته می‌شود.
  • notify_url (اختیاری): آدرس وبهوکی که می‌توانید ارسال کنید تا از وضعیت نهایی این برداشت وجه مطلع شوید. در مواقع تست می‌توانید از وبسایت webhook.siteاستفاده کنید.
  • max_retry_count (اختیاری): حداکثر تعداد دفعاتی که می‌خواهید برای این برداشت وجه تلاش شود. حداقل ۱ و حداکثر ۱۶ مرتبه می‌توان برای یک برداشت وجه تلاش کرد. دقت داشته باشید که در صورت عدم ارسال این پارامتر، مقدار آن برابر با ۱ در نظر گرفته می‌شود. همچنین در نظر داشته باشید این پارامتر برای برداشت وجه‌های آنی (is_instant: 1) برابر با ۱ در نظر گرفته می‌شود (و برداشت وجه آنی بلافاصله پس از استعلام (نمایش برداشت وجه - withdrawal show)، تعیین وضعیت می‌شود که حالت FAILED است یا DONE). در صورتی که برداشت وجه به صورت آنی نباشد (is_instant: 0) اگر برداشت وجه موفقیت‌آمیز باشد (status: DONE) که دیگر تلاشی صورت نمی‌گیرد، اما اگر برداشت وجه به هر دلیل موفقیت‌آمیز نباشد، تا زمانی که برداشت وجه موفقیت‌آمیز شود و یا مقدار retry_count به تعداد max_retry_count برسد سعی به برداشت وجه صورت می‌گیرد. لازم به ذکر است که تا زمانی که برداشت وجه موفقیت‌آمیز نباشد وضعیت آن برداشت وجه به حالت PENDING است و فقط زمانی که مقدار retry_count به max_retry_count (ارسالی از شما) برسد و هنوز برداشت وجه موفقیت‌آمیز نبوده باشد دیگر تلاشی برای برداشت وجه صورت نمی‌گیرد و وضعیت آن برداشت وجه از حالت PENDING به حالت FAILED تبدیل می‌شود.
  • description (اختیاری): توضیحات اختیاری برای ثبت برداشت وجه

نمونه json

{
  "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
  "amount": "10000",
  "is_instant": 1,
  "notify_url": "http://yourdomain.com/notify/me",
}
{
  "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
  "amount": "10000",
  "withdrawal_date": "2020-07-04",
  "is_instant": 0,
  "notify_url": "http://yourdomain.com/notify/me",
  "max_retry_count": 1,
  "description": "تست وندار"
}

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "status": 1,
  "message": "درخواست برداشت وجه با موفقیت ثبت شد.",
  "result": {
    "withdrawal": {
      "id": "8c6e27c0-dbbd-11ea-a2f6-e9c8bf97463f",
      "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
      "retry_count": 1,
      "max_retry_count": 1,
      "gateway_transaction_id": "159714176734",
      "amount": "10000",
      "wage_amount": 200,
      "payment_number": null,
      "status": "PENDING",
      "description": null,
      "withdrawal_date": "1399\/05\/21",
      "notify_url": "http://yourdomain.com/notify/me",
      "is_instant": true,
      "error_code": null,
      "error_message": null
    }
  }
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام درخواست برداشت وجه با موفقیت ثبت شد
  • result:
    • withdrawal:
      • id: آیدی درخواست برداشت وجه
      • authorization_id: آیدی اشتراکی که درخواست برداشت وجه برای آن صادر شده است
      • retry_count: تعداد دفعات تلاش برای برداشت وجه
      • gateway_transaction_id: شناسه یکتای برداشت وجه
      • amount: مبلغ برداشت وجه
      • wage_amount: کارمزد
      • payment_number: شناسه بانکی برداشت وجه
      • status: وضعیت برداشت وجه که ۵ حالت PENDING, INIT, DONE, CANCELED, FAILED دارد. وضعیت PENDING نشان‌دهنده‌ی این است که تراکنش در حالت انتظار است. INIT نشان‌دهنده‌ی این است که تراکنش به سمت بانک فرستاده شده است. DONE نشان‌دهنده‌ی وضعیت موفقیت‌آمیز تراکنش است. FAILED تراکنش ناموفق را نشان می‌دهد. CANCELED تراکنشی را نشان می‌دهد که لغو شده است. لازم به ذکر است که امکان لغو تراکنش صرفاً برای تراکنش‌هایی امکان‌پذیر است که به صورت آنی انجام نشده باشند (is_instant: false).
      • description: توضیحات
      • withdrawal_date: تاریخ درخواست برداشت وجه ارسالی توسط شما
      • notify_url: آدرس وبهوکی که می‌توانید ارسال کنید تا از وضعیت نهایی این برداشت وجه مطلع شوید. لازم به ذکر است که متد POST برای ارسال به این آدرس در نظر گرفته شده است و فیلدهای withdrawal_id, authorization_id, gateway_transaction_id, status, amount و payment_number برای شما ارسال می‌شود. در شرایطی که شما در حال تست هستید می‌توانید از وبسایت webhook.site استفاده کنید.
      • is_instant: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر.
      • max_retry_count: حداکثر تعداد دفعاتی که می‌خواهید برای این برداشت وجه تلاش شود. حداقل ۱ و حداکثر ۱۶ مرتبه می‌توان برای یک برداشت وجه تلاش کرد. دقت داشته باشید که در صورت عدم ارسال این پارامتر، مقدار آن برابر با ۱ در نظر گرفته می‌شود. همچنین در نظر داشته باشید این پارامتر برای برداشت وجه‌های آنی (is_instant: 1) برابر با ۱ در نظر گرفته می‌شود (و برداشت وجه آنی بلافاصله پس از استعلام (نمایش برداشت وجه - withdrawal show)، تعیین وضعیت می‌شود که حالت FAILED است یا DONE). در صورتی که برداشت وجه به صورت آنی نباشد (is_instant: 0) اگر برداشت وجه موفقیت‌آمیز باشد (status: DONE) که دیگر تلاشی صورت نمی‌گیرد، اما اگر برداشت وجه به هر دلیل موفقیت‌آمیز نباشد، تا زمانی که برداشت وجه موفقیت‌آمیز شود و یا مقدار retry_count به تعداد max_retry_count برسد سعی به برداشت وجه صورت می‌گیرد. لازم به ذکر است که تا زمانی که برداشت وجه موفقیت‌آمیز نباشد وضعیت آن برداشت وجه به حالت PENDING است و فقط زمانی که مقدار retry_count به max_retry_count (ارسالی از شما) برسد و هنوز برداشت وجه موفقیت‌آمیز نبوده باشد دیگر تلاشی برای برداشت وجه صورت نمی‌گیرد و وضعیت آن برداشت وجه از حالت PENDING به حالت FAILED تبدیل می‌شود.
      • error_code: در زمان ثبت برداشت null می باشد (بعد از استعلام برداشت وجه در صورت وجود خطا کد خطا برگردانده میشود)
      • error_message: در زمان ثبت برداشت null می باشد (بعد از استعلام برداشت وجه در صورت وجود خطا متن خطا برگردانده میشود)

نمونه پاسخ دریافتی ناموفق:

اگر بیشتر از تعداد count این درخواست را صدا بزنید با خطای زیر مواجه می شوید.

HTTP/1.1 422
{
  "status": 0,
  "errors": {
    "authorization_id": "ذخیره برداشت وجه به دلیل رسیدن به حداکثر تعداد برداشت در ماه، امکان پذیر نیست."
  }
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors:
    • authorization_id: متن خطا

در صورتی که توکن فرستاده شده معتبر نباشد پاسخ زیر را دریافت می کنید:

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

در صورت عدم وجود کسب و کار این خطا را دریافت می کنید:

HTTP/1.1 404
{
  "status": 0,
  "error": "کسب و کار وجود ندارد"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: آرایه ای از خطا‌ها

۲. لیست برداشت وجه های ثبت شده

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

Method: GET
Address: https://api.vandar.io/v2/business/{business}/subscription/withdrawal

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد نمایش لیست برداشت وجه از اشتراک آن را دارید.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200

{
  "data": [
    {
      "id": "f3d084e0-b603-11ea-94ad-ebc7f5bf8e12",
      "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
      "retry_count": 1,
      "max_retry_count": 1,
      "gateway_transaction_id": 159281892196,
      "amount": 10000,
      "wage_amount": "200.00",
      "payment_number": null,
      "status": "DONE",
      "description": null,
      "withdrawal_date": "1399\/04\/04",
      "notify_url": "http://yourdomain.com/notify/me",
      "is_instant": true,
      "error_code": null,
      "error_message": null
    },
    {
      "id": "88a2c1d0-ff9f-11eb-9054-d393c32ed3b6",
      "authorization_id": "fa99a8f0-fb51-11eb-8a87-41af5f44fd0d",
      "retry_count": 1,
      "max_retry_count": 1,
      "gateway_transaction_id": 162923462083,
      "amount": 11000,
      "wage_amount": "0.00",
      "payment_number": null,
      "status": "FAILED",
      "description": "تست میلاد",
      "withdrawal_date": "1400/05/27",
      "notify_url": null,
      "is_instant": 1,
      "error_code": "01",
      "error_message": "عدم کفایت موجودی"
        },
    ...
  ],
  "links": {
    "first": "https://api.vandar.io/v2/business/vandario/subscription/withdrawal?page=1",
    "last": "https://api.vandar.io/v2/business/vandario/subscription/withdrawal?page=33",
    "prev": null,
    "next": "https://api.vandar.io/v2/business/vandario/subscription/withdrawal?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 33,
    "path": "https://api.vandar.io/v2/business/vandario/subscription/withdrawal",
    "per_page": 20,
    "to": 20,
    "total": 656
  }
}
  • data:
    • id: آیدی درخواست برداشت وجه
    • authorization_id: آیدی اشتراکی که درخواست برداشت وجه برای آن صادر شده است
    • retry_count: تعداد دفعات تلاش برای برداشت وجه
    • gateway_transaction_id: شناسه یکتای برداشت وجه
    • amount: مبلغ برداشت وجه
    • wage_amount: کارمزد
    • payment_number: شناسه بانکی برداشت وجه
    • status: وضعیت برداشت وجه که ۴ حالت PENDING, DONE, CANCELED, FAILED دارد.
    • description: توضیحات
    • withdrawal_date: تاریخ درخواست برداشت وجه ارسالی توسط شما
    • notify_url: آدرس وبهوکی که می‌توانید ارسال کنید تا از وضعیت نهایی این برداشت وجه مطلع شوید. لازم به ذکر است که متد POST برای ارسال به این آدرس در نظر گرفته شده است و فیلدهای withdrawal_id, authorization_id, gateway_transaction_id, status, amount و payment_number برای شما ارسال می‌شود.
    • is_instant: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر
    • max_retry_count (اختیاری): حداکثر تعداد دفعاتی که می‌خواهید برای این برداشت وجه تلاش شود. حداقل ۱ و حداکثر ۱۶ مرتبه می‌توان برای یک برداشت وجه تلاش کرد. دقت داشته باشید که در صورت عدم ارسال این پارامتر، مقدار آن برابر با ۱ در نظر گرفته می‌شود. همچنین در نظر داشته باشید این پارامتر برای برداشت وجه‌های آنی (is_instant: 1) برابر با ۱ در نظر گرفته می‌شود (و برداشت وجه آنی بلافاصله پس از استعلام (نمایش برداشت وجه - withdrawal show)، تعیین وضعیت می‌شود که حالت FAILED است یا DONE). در صورتی که برداشت وجه به صورت آنی نباشد (is_instant: 0) اگر برداشت وجه موفقیت‌آمیز باشد (status: DONE) که دیگر تلاشی صورت نمی‌گیرد، اما اگر برداشت وجه به هر دلیل موفقیت‌آمیز نباشد، تا زمانی که برداشت وجه موفقیت‌آمیز شود و یا مقدار retry_count به تعداد max_retry_count برسد سعی به برداشت وجه صورت می‌گیرد. لازم به ذکر است که تا زمانی که برداشت وجه موفقیت‌آمیز نباشد وضعیت آن برداشت وجه به حالت PENDING است و فقط زمانی که مقدار retry_count به max_retry_count (ارسالی از شما) برسد و هنوز برداشت وجه موفقیت‌آمیز نبوده باشد دیگر تلاشی برای برداشت وجه صورت نمی‌گیرد و وضعیت آن برداشت وجه از حالت PENDING به حالت FAILED تبدیل می‌شود.
    • error_code: کد خطای ناموفق بودن درخواست برداشت وجه
    • error_message: متن خطای ناموفق بودن درخواست برداشت وجه
  • links:
    • first: آدرس اولین صفحه
    • last: آدرس آخرین صفحه
    • prev: آدرس صفحه قبل
    • next: آدرس صفحه بعد
  • meta:
    • current_page: آدرس همین صفحه
    • from: شماره اولین آیتمی که در این صفحه آمده است
    • last_page: تعداد کل صفحات
    • path: آدرس خالص بدون صفحه بندی
    • per_page: تعداد آیتم در هر صفحه
    • to: شماره آخرین آیتمی که در این صفحه آمده است
    • total: تعداد کل آیتم ها

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

۳. نمایش یک برداشت وجه:

METHOD: GET
URL: https://api.vandar.io/v2/business/{business}/subscription/withdrawal/{id}

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد دارید یک برداشت وجه از آن را نمایش دهید.

پارامتر {id} همان id مربوط به برداشت وجهی است که قصد نمایش آن را دارید.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "status": 1,
  "message": "برداشت وجه با موفقیت به نمایش درآمد.",
  "result": {
    "withdrawal": {
      "id": "f3d084e0-b603-11ea-94ad-ebc7f5bf8e12",
      "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
      "retry_count": 1,
      "max_retry_count": 1,
      "gateway_transaction_id": 159281892196,
      "amount": 10000,
      "wage_amount": "200.00",
      "payment_number": null,
      "status": "DONE",
      "description": null,
      "withdrawal_date": "1399\/04\/04"
      "notify_url": "http://yourdomain.com/notify/me",
      "is_instant": true
      "error_code": null,
      "error_message": null
      }
    },
  }
}

نمونه پاسخ دریافتی موفق برای برداشت وجه ناموفق: (error_code و error_message علت و کد خطا را نشان می دهد.)

HTTP/1.1 200
{
"status": 1,
"message": "برداشت وجه با موفقیت به نمایش درآمد.",
"result": {
"withdrawal": {
"id": "c0fae570-9b64-11eb-9635-1bfa552b96c5",
"authorization_id": "ac42fcd0-9b64-11eb-af96-abcc98948330",
"retry_count": 1,
"max_retry_count": 1,
"gateway_transaction_id": 159903362213,
"amount": 2040000,
"wage_amount": "40000.00",
"payment_number": null,
"status": "INIT",
"description": null,
"withdrawal_date": "1400\/01\/22",
"notify_url": null,
"is_instant": 0,
"error_code": "01",
"error_message": "عدم کفایت موجودی"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام برداشت وجه با موفقیت به نمایش درآمد
  • result:
    • withdrawal:
      • id: آیدی درخواست برداشت وجه
      • authorization_id: آیدی اشتراکی که درخواست برداشت وجه برای آن صادر شده است
      • retry_count: تعداد دفعات تلاش برای برداشت وجه
      • gateway_transaction_id: شناسه یکتای برداشت وجه
      • amount: مبلغ برداشت وجه
      • wage_amount: کارمزد
      • payment_number: شناسه بانکی برداشت وجه
      • status: وضعیت برداشت وجه که ۴ حالت PENDING, DONE, CANCELED, FAILED دارد.
      • description: توضیحات
      • withdrawal_date: تاریخ درخواست برداشت وجه ارسالی توسط شما
      • notify_url: آدرس وبهوکی که می‌توانید ارسال کنید تا از وضعیت نهایی این برداشت وجه مطلع شوید. لازم به ذکر است که متد POST برای ارسال به این آدرس در نظر گرفته شده است و فیلدهای withdrawal_id, authorization_id, gateway_transaction_id, status, amount و payment_number برای شما ارسال می‌شود.
      • is_instant: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر
      • max_retry_count (اختیاری): حداکثر تعداد دفعاتی که می‌خواهید برای این برداشت وجه تلاش شود. حداقل ۱ و حداکثر ۱۶ مرتبه می‌توان برای یک برداشت وجه تلاش کرد. دقت داشته باشید که در صورت عدم ارسال این پارامتر، مقدار آن برابر با ۱ در نظر گرفته می‌شود. همچنین در نظر داشته باشید این پارامتر برای برداشت وجه‌های آنی (is_instant: 1) برابر با ۱ در نظر گرفته می‌شود (و برداشت وجه آنی بلافاصله پس از استعلام (نمایش برداشت وجه - withdrawal show)، تعیین وضعیت می‌شود که حالت FAILED است یا DONE). در صورتی که برداشت وجه به صورت آنی نباشد (is_instant: 0) اگر برداشت وجه موفقیت‌آمیز باشد (status: DONE) که دیگر تلاشی صورت نمی‌گیرد، اما اگر برداشت وجه به هر دلیل موفقیت‌آمیز نباشد، تا زمانی که برداشت وجه موفقیت‌آمیز شود و یا مقدار retry_count به تعداد max_retry_count برسد سعی به برداشت وجه صورت می‌گیرد. لازم به ذکر است که تا زمانی که برداشت وجه موفقیت‌آمیز نباشد وضعیت آن برداشت وجه به حالت PENDING است و فقط زمانی که مقدار retry_count به max_retry_count (ارسالی از شما) برسد و هنوز برداشت وجه موفقیت‌آمیز نبوده باشد دیگر تلاشی برای برداشت وجه صورت نمی‌گیرد و وضعیت آن برداشت وجه از حالت PENDING به حالت FAILED تبدیل می‌شود.
      • error_code: کد خطای ناموفق بودن درخواست برداشت وجه
      • error_message: متن خطای ناموفق بودن درخواست برداشت وجه

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}

در صورت عدم کفایت موجودی خطای زیر را در خروجی درخواست دریافت خواهید کرد:

  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

۴. انصراف از برداشت وجه:

در صورتی که کاربر از برداشت وجه منصرف شود با صدا زدن متد زیر می تواند انصراف خود را اعلام کند.

METHOD: PUT
URL: https://api.vandar.io/v2/business/{business}/subscription/withdrawal/{id}

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد دارید یک برداشت وجه از آن را لغو کنید.

پارامتر {id} همان id مربوط به برداشت وجهی است که قصد لغو آن را دارید.

نمونه پاسخ دریافتی موفق:

  HTTP/1.1 200
{
  "status": 1,
  "message": "برداشت وجه با موفقیت لغو گردید.",
  "result": {
    "withdrawal": {
      "id": "8c6e27c0-dbbd-11ea-a2f6-e9c8bf97463f"
    }
  }
}
  
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: پیغام برداشت وجه با موفقیت لغو گردید.
  • result:
    • withdrawal:
      • id:
      • شناسه‌ی برداشت وجهی که قصد کنسل کردن آن را داشتید.

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 401
{
  "status": 0,
  "error": "Unauthenticated"
}
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • errors: آرایه ای از خطا‌ها

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

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

METHOD: GET
URL: https://health.vandar.io/subscription
                      

نمونه خطاهای دریافتی هنگام برداشت وجه ناموفق:

Error Code Error Message
00 خطای غیرمنتظره
01 عدم کفایت موجودی
02 خطای سرور
03 منبع مورد نظر یافت نشد
04 محدودیت تعداد تراکنش روزانه برای این واگذاری رعایت نشده است
05 برنامه مورد نظر یافت نشد
06 توکن نامعتبر
07 سپرده نامعتبر
08 مبلغ نامعتبر است
09 حساب مقصد نامعتبر
10 واگذار کننده به عنوان مشتری بانک موردنظر ثبت نشده است
11 شماره پیگیری تکراری/نامعتبر است
12 وضعیت موسسه نامعتبر است
13 وضعیت واگذاری نامعتبر است
14 واگذاری منقضی شده است
15 زمان انجام تراکنش برای این واگذاری نامعتبر است
16 محدودیت تعداد تراکنش روزانه برای این واگذاری رعایت نشده است
17 محدودیت تعداد تراکنش ماهانه برای این واگذاری رعایت نشده است
18 زمان پیمان شروع نشده است
19 مبلغ ورودی نامعتبر است
20 ارز مبدا مقصد یکسان نیست/کد ارز مورد نظر در سیستم تعریف نشده
21 سپرده متعلق به کاربر نیست/عدم امکان دسترسی به سپرده/عدم وجود حق برداشت/برداشت امکانپذیر نیست
22 شماره سپرده نامعتبر است
23 پارامترهای ورودی به درستی وارد نشده اند
24 شماره سپرده مورد نظر وجود ندارد
25 خطای داخلی بوم
26 خطاهای داخلی پیمان
27 شناسه موسسه مورد نظر یافت نشده/نامعتبر است
28 حساب مسدود است
29 شماره پیگیری تکراریست
30 تعداد تراکنش های انجام شده از تعداد مجاز روزانه بیشتر است
31 تعداد تراکنش های انجام شده از تعداد مجاز ماهانه بیشتر است
32 خطای برداشت مستقیم رخ داده است