آخرین تغییرات: ۱۳۹۹/۱۰/۰۶

مقدمه

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

سرویس اشتراک یا دایرکت دبیت سرویسی است که یک فرد وجوهی را از حساب بانکی شخص دیگری خارج میکند در واقع شما به بانک اجازه میدهید که مبلغی را مستقیما از حسابتان کسر و در قبال آن خدماتی را به شما ارایه دهد. به طور کلی دایرت دبیت برداشت مستقیم پول برای انجام معاملات مالی در صورت صدور مجوز توسط پرداخت کننده می باشد. این کار بیشتر زمانی انجام می شود که شما بخواهید اشتراک خود را تمدید کنید. شما می توانید در وندار به وسیله این 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

توضیحات

  • bank_code (اجباری): کد بانک که از جدول زیر قابل دسترسی است
    Bank Code
    آینده 062
    بانک ایران زمین 069
    بانک دی 066
    بانک انصار 063
    بانک شهر 061
    بانک سرمایه 058
    بانک سامان 056
    بانک اقتصاد نوین 055
    پست بانک ایران 021
    بانک کشاورزی 016

  • mobile (اجباری): شماره موبایل کاربرtoken دریافتی در این قسمت یکبار مصرف است و پس از ۲۰ دقیقه باطل می شود.
    • نکته! دقت داشته باشید که در صورت منتقل شدن به صفحه‌ی بانک با این شماره موبایل، برای بانک‌هایی که برای ورود نیاز به کد ملی کاربر دارند، بایستی کد ملی و شماره موبایل مربوط به یک شخص باشند. در واقع بایستی شماره موبایل در هنگام خرید با استفاده از آن کد ملی خریداری شده باشد در غیر این صورت در صفحه‌ی بانک با پیغام خطا روبرو می‌شود و امکان ورود پیدا نمی‌کند.
  • callback_url (اجباری): باید با آدرس درگاه پرداخت تایید شده در وندار بر روی یک دامنه باشد
  • count (اجباری): رشته عددی مشخص کننده تعداد درخواست های برداشت وجه که به صورت ماهیانه مشخص می‌شود.
  • limit (اجباری): رشته عددی مشخص کننده حداکثر مبلغ برداشت وجه در هر برداشت. واحد پول ریال است.
  • name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
  • email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.

نمونه json 

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

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

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=dd205c00-b603-11ea-b6fc-ed9baa10357b&status=FAILED_TO_ACCESS_BANK
  • token: توکنی که با استفاده از آن تلاش کرده‌اید تا به صفحه‌ی بانک منتقل شوید.

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

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

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

صفحه دسترسی

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

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

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

https://yourdomain.com/callback?token=8cfd3e60-dc77-11ea-a593-15deb083f3e2&authorization_id=9f307e30-dc77-11ea-830e-7533ca1787c5&status=SUCCEED

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

https://yourdomain.com/callback?token=1be4da80-dc77-11ea-9a70-cf1039d4b64d&status=FAILED
  • token: توکنی که با استفاده از آن تلاش کرده‌اید تا به صفحه‌ی بانک منتقل شوید.

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

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

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

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

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

HTTP/1.1 200
{
  "data": [
    {
      "id": "b4d32590-d426-11ea-b5b5-0b0e1f82ac3c",
      "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",
      "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: کدملی کاربر در صورتی که بانک به وندار برگردانده باشد
    • 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": "b4d32590-d426-11ea-b5b5-0b0e1f82ac3c",
      "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",
      "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: کدملی کاربر در صورتی که بانک به وندار برگردانده باشد
      • created_at: زمان ساخت اشتراک

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

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

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

۶. پاک کردن یک اشتراک با استفاده از 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": "0cf235d0-d48b-11ea-86cd-298ec898a9bd"
    }
  }
}
  • 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 string required
withdrawal_date string required
is_instant boolean optional
notify_url string optional

توضیحات

  • authorization_id (اجباری): آیدی دریافتی در بخش اشتراک که می خواهید مبلغ از آن دسترسی برداشت شود
  • amount (اجباری): مبلغ برداشت وجه
  • withdrawal_date (اجباری): تاریخی از امروز به بعد که می خواهید مبلغ در آن روز از حساب برداشت شود
  • is_instant (اختیاری): این پارامتر مشخص می‌کند که برداشت وجه در همین لحظه انجام شود یا در سیکل‌های مشخصی که توسط وندار کنترل می‌شوند. در صورت عدم ارسال، true در نظر گرفته می‌شود.
  • notify_url (اختیاری): آدرس وبهوکی که می‌توانید ارسال کنید تا از وضعیت نهایی این برداشت وجه مطلع شوید. در مواقع تست می‌توانید از وبسایت webhook.siteاستفاده کنید.

نمونه json 

{
  "authorization_id": "dd205c00-b603-11ea-b6fc-ed9baa10357b",
  "amount": "10000",
  "withdrawal_date": "2020-07-04",
  "is_instant": true,
  "notify_url": "http://yourdomain.com/notify/me"
}

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

HTTP/1.1 200
{
  "status": 1,
  "message": "درخواست برداشت وجه با موفقیت ثبت شد.",
  "result": {
    "withdrawal": {
      "id": "8c6e27c0-dbbd-11ea-a2f6-e9c8bf97463f",
      "authorization_id": "2866fa80-dbbd-11ea-a0f9-d19612a00c59",
      "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
    }
  }
}
  • 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: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر.

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

اگر بیشتر از تعداد 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": "dd205c00-b603-11ea-b6fc-ed9baa10357b",
      "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
    },
    ...
  ],
  "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: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر
  • 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": "dd205c00-b603-11ea-b6fc-ed9baa10357b",
      "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
      }
    },
  }
}
  • 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: نشان دهنده این است که برداشت وجه به صورت آنی انجام شده است یا خیر

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

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