آخرین تغییرات: ۱۴۰۰/۰۸/۲۳
  • نسخه ۳.۰ (۱۴۰۰/۰۸/۲۳)
    • الزامی شدن پارامتر expiration_date هنگام ایجاد اشتراک جدید.
    • اضافه شدن قدم الزامی «تایید تراکنش»
    • فیلد status .در پاسخ‌های دریافتی که مقدار ۰ یا ۱ بر پایه وضعیت به خود می‌گرفت منسوخ شده و در به‌روزرسانی‌های بعدی نسخه ۳ وجود نخواهد داشت. راه‌حل جایگزین بررسی کد وضعیت HTTP بازگردانده شده از سوی وندار است.
    • فیلد status هنگام نمایش اشتراک‌ها اضافه شده است که می‌تواند یکی از مقادیر ACTIVE یا PENDING_VERIFY را داشته باشد.

مقدمه

دایرکت دبیت یا سرویس پرداخت خودکار چیست:

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

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

Accept: application/json
Authorization Bearer {Token}

دریافت لیست بانک‌ها

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

۱. لیست عمومی بانک‌ها

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

Method:  GET
Address: https://health.vandar.io/subscription

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

HTTP/1.1 200
{
    "status": 1,
    "message": "وضعیت بانک‌ها در حال حاضر به این صورت است.",
    "result": {
        "banks": [
            {
                "code": "012",
                "name": "بانک ملت",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/12.svg"
            },
            {
                "code": "017",
                "name": "بانک ملی ایران",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/17.svg"
            },
            {
                "code": "055",
                "name": "بانک اقتصاد نوین",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/55.svg"
            },
            {
                "code": "056",
                "name": "بانک سامان",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/56.svg"
            },
            {
                "code": "062",
                "name": "بانک آینده",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/62.svg"
            },
            {
                "code": "066",
                "name": "بانک دی",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/66.svg"
            },
            {
                "code": "103",
                "name": "حساب دیجیتال پاسارگاد",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/103.svg"
            }
        ]
    }
}

۲. لیست شخصی‌سازی شده بانک‌ها

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


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

مدیریت لیست بانک‌ها

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

Method:  GET
Address: https://api.vandar.io/v3/business/{business}/subscription/banks/actives

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

HTTP/1.1 200
{
    "status": 1,
    "message": "وضعیت بانک‌ها در حال حاضر به این صورت است.",
    "result": {
        "banks": [
            {
                "code": "012",
                "name": "بانک ملت",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/12.svg"
            },
            {
                "code": "017",
                "name": "بانک ملی ایران",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/17.svg"
            },
            {
                "code": "055",
                "name": "بانک اقتصاد نوین",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/55.svg"
            },
            {
                "code": "056",
                "name": "بانک سامان",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/56.svg"
            },
            {
                "code": "062",
                "name": "بانک آینده",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/62.svg"
            },
            {
                "code": "066",
                "name": "بانک دی",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/66.svg"
            },
            {
                "code": "103",
                "name": "حساب دیجیتال پاسارگاد",
                "has_direct_debit_ability": true,
                "is_healthy_on_direct_debit": true,
                "logo": "https://vandar.io/assets/img/banks/103.svg"
            }
        ]
    }
}


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

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

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

Method: POST
Address: https://api.vandar.io/v3/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
expiration_date date required (optional on version 2)
name string optional
email string 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 (اجباری): حداکثر مبلغ قابل برداشت وجه در برداشت وجه‌های مربوط به این مجوز. واحد پول ریال است.
  • expiration_date (اجباری): تاریخ انقضای اشتراک. این تاریخ باید بزرگتر از تاریخ روز جاری باشد و به صورت میلادی وارد می‌شود.
    • نکته! این مقدار در نسخه ۲ APIهای وندار اجباری نبوده و در صورت عدم وجود به شکل پیش‌فرض ۳ سال از زمان حال در نظر گرفته می‌شود.
  • name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
  • email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.
  • 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: کد خطایی که به دلیل آن این درخواست ناموفق بوده است که می توانید با استفاده از جدول زیر توضیحات هر کد را ببینید.
error_code error_message

۴. تایید اشتراک

چنانچه کسب‌وکار شما از نسخه ۲ APIهای وندار بهره می‌برد، تا ۱ اسفند ۱۴۰۰ نیازی به پیاده‌سازی این قدم نخواهید داشت.

درصورتی که کاربر اجازه دسترسی به مجوز را صادر کرده باشد، باید مجوز ایجاد شده را از طریق ارسال authorization_id به وندار تایید کنید. برای جلوگیری از تغییر وضعیت مجوزهای پیشین، وندار تنها یک بار اجازه تایید مجوز را به API می‌دهد.

Method: PATCH
Address: https://api.vandar.io/v3/business/{business}/subscription/authorization/{authorization}/verify
نکته! وندار به جهت جلوگیری از ایجاد مجوز رهاشده، مجوزهایی که پس از ۲۰ دقیقه تایید نشوند را به شکل خودکار لغو می‌کند.

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

HTTP/1.1 200
{
    'status' => 1,
    'message' => 'مجوز با موفقیت تایید شد.'

}

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

HTTP/1.1 422
{
    'status' => 0,
    'message': 'مجوز پیش از این تایید شده است.'
}

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

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

METHOD: GET
URL: https://api.vandar.io/v3/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",
      "status": "ACTIVE",
      "created_at": "1399\/04\/04 14:47:09"
    },
    ...
  ],
  "links": {
    "first": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=1",
    "last": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=134",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 134,
    "links": [
      {
        "url": null,
        "label": "« قبلی",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=133",
        "label": "133",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=134",
        "label": "134",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/authorization?page=2",
        "label": "بعدی »",
        "active": false
      }
		],
    "path": "https://api.vandar.io/v3/business/vandario/subscription/authorization",
    "per_page": 20,
    "to": 20,
    "total": 2675
  }
}
  • data:
    • id: آیدی اشتراک که برای درخواست برداشت وجه از این آیدی استفاده می شود.
    • customer_uuid: شناسه مشتری کسب و کار شما
    • token: توکنی که در مرحله اول برای شما ارسال شده است.
    • bank_code: کد بانک که لیست آن در بالا اشاره شده است.
    • callback_url: آدرس بازگشتی ای که در زمان درخواست ارسال کرده اید.
    • count: رشته عددی مشخص کننده تعداد درخواست های برداشت وجه که به صورت ماهیانه مشخص می‌شود.
    • limit: رشته عددی مشخص کننده حداکثر مبلغ برداشت وجه در هر برداشت. واحد پول ریال است.
    • mobile: شماره موبایل کاربر
    • name: نام کاربر اگر در مرحله قبل ارسال کردید
    • email: ایمیل کاربر اگر در مرحله قبل ارسال کردید
    • national_code: کدملی کاربر در صورتی که بانک به وندار برگردانده باشد
    • expiration_date: تاریخ انقضای اشتراک. این تاریخ می‌تواند تاریخ امروز یا بعد از آن باشد و به صورت میلادی وارد می‌شود.
    • status: وضعیت اشتراک که می‌تواند ACTIVE و یا PENDING_VERIFY باشد.
    • created_at: زمان ساخت اشتراک
  • links:
    • first: آدرس اولین صفحه
    • last: آدرس آخرین صفحه
    • prev: آدرس صفحه قبل
    • next: آدرس صفحه بعد
  • meta:
    • current_page: آدرس همین صفحه
    • from: شماره اولین آیتم که در این صفحه آمده است
    • last_page: تعداد کل صفحات
    • links: آرایه ای قابل استفاده برای نمایش pagination
    • path: آدرس خالص بدون صفحه بندی
    • per_page: تعداد آیتم در هر صفحه
    • to: شماره آخرین آیتمی که در این صفحه آمده است
    • total: تعداد کل آیتم ها
نکته! در این قسمت در خروجی id را دریافت میکنیم که مطابق با همان authorization_id دریافتی از 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/v3/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",
      "status": "ACTIVE",
      "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: تاریخ انقضای اشتراک. این تاریخ می‌تواند تاریخ امروز یا بعد از آن باشد و به صورت میلادی وارد می‌شود. این مورد ممکن است در اشتراک‌های ایجاد شده با نسخه ۲ API وجود نداشته باشد.
      • status: وضعیت فعلی اشتراک که می‌تواند ACTIVE یا PENDING_VERIFY باشد.
      • 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/v3/business/{business}/subscription/authorization/{id}

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

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

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

HTTP/1.1 200
{
  "status": 1,
  "message": "مجوز با موفقیت لغو گردید.",
  "result": {
    "authorization": {
      "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/v3/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
track_id 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 (اختیاری): توضیحات اختیاری برای ثبت برداشت وجه
  • track_id (اختیاری): شناسه پیگیری که به ازای هر درخواست برداشت باید یکتا باشد. پیشنهاد ما استفاده از uuid برای این پارامتر می‌باشد. این پارامتر به حروف بزرگ و کوچک حساس است. با استفاده از این پارامتر می توان در سرویس نمایش برداشت وجه بر اساس شناسه پیگیری که در ادامه توضیح داده می شود از جزییات برداشت وجه مطع شوید.

نمونه 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": "تست وندار",
  "track_id": "d2c5bf5a-280f-4ee5-8888-3d220b63bcc0"
}

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

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,
      "track_id": 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: شناسه بانکی برداشت وجه
      • track_id: شناسه پیگیری
      • status: وضعیت برداشت وجه که ۶ حالت PENDING, INIT, DONE, CANCELED, REFUND, FAILED دارد. وضعیت PENDING نشان‌دهنده‌ی این است که تراکنش در حالت انتظار است. INIT نشان‌دهنده‌ی این است که تراکنش به سمت بانک فرستاده شده است. DONE نشان‌دهنده‌ی وضعیت موفقیت‌آمیز تراکنش است. FAILED تراکنش ناموفق را نشان می‌دهد. CANCELED تراکنشی را نشان می‌دهد که لغو شده است و REFUND به این معنی است که مبلغ تراکنش به کاربر بازگشت خورده است. لازم به ذکر است که امکان لغو تراکنش صرفاً برای تراکنش‌هایی امکان‌پذیر است که به صورت آنی انجام نشده باشند (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 409
{
  "status": 0,
  "message": "درحال حاضر امکان ثبت درخواست برداشت وجه در بانک مورد نظر وجود ندارد."
}
  • status (منسوخ شده): ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره. اما افزون بر این، فیلد status برای کمک به شماست که متوجه شوید آیا این api کاری که به آن محول شده را به درستی انجام داده است یا خیر. به طور خلاصه:
    1 به معنای این است که http response از خانواده‌ی ۲۰۰ است.
    0 به معنای این است که http response از خانواده‌ی ۴۰۰ یا ۵۰۰ است.
  • message: متن خطا

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

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: آرایه ای از خطا‌ها

در صورت ارسال شناسه پیگیری تکراری این خطا را دریافت می کنید: 

HTTP/1.1 422
{
	"message": "The given data was invalid.",
	"errors": {
		"track_id": [
			"یک دستور برداشت با این شناسه قبلا ثبت شد است."
		]
	}
}

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

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

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

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

لیست برداشت وجه های یک اشتراک

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

Method: GET
Address: https://api.vandar.io/v3/business/{business}/subscription/withdrawal?q={authorization_id}

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

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,
      "track_id": "d2c5bf5a-280f-4ee5-8888-3d220b63bcc0",
      "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,
      "track_id": "eb7dfff7-a752-402b-a46b-024545f06c76",
      "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/v3/business/vandario/subscription/withdrawal?page=1",
    "last": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=33",
    "prev": null,
    "next": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 33,
    "links": [
      {
        "url": null,
        "label": "« قبلی",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=32",
        "label": "32",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=33",
        "label": "33",
        "active": false
      },
      {
        "url": "https://api.vandar.io/v3/business/vandario/subscription/withdrawal?page=2",
        "label": "بعدی »",
        "active": false
      }
		],
    "path": "https://api.vandar.io/v3/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: شناسه بانکی برداشت وجه
    • track_id: شناسه پیگیری
    • status: وضعیت برداشت وجه که ۵ حالت PENDING, DONE, CANCELED, FAILED, REFUND دارد.
    • 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: تعداد کل صفحات
    • links: آرایه ای قابل استفاده برای نمایش pagination
    • 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/v3/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,
      "track_id": "d2c5bf5a-280f-4ee5-8888-3d220b63bcc0",
      "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,
  "track_id": "d2c5bf5a-280f-4ee5-8888-3d220b63bcc0",
  "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: شناسه بانکی برداشت وجه
      • track_id: شناسه پیگیری
      • status: وضعیت برداشت وجه که ۵ حالت PENDING, DONE, CANCELED, FAILED, REFUND دارد.
      • 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: GET
URL: https://api.vandar.io/v3/business/{business}/subscription/withdrawal/track-id/{track_id}

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

پارامتر {track_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,
      "track_id": "d2c5bf5a-280f-4ee5-8888-3d220b63bcc0",
      "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
      }
    },
  }
}

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

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

METHOD: PUT
URL: https://api.vandar.io/v3/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

با ارسال پارامتر type میتوانید نوع لوگوی بانک را با توجه به نیاز تغییر دهید.

در حال حاضر type های svg و png پشتیبانی می شود که به صورت پیشفرض svg می باشد.

METHOD: GET
URL: https://health.vandar.io/subscription?type=png

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

error_code error_message