مستندات وندار | ارایه دهنده راهکارهای پرداخت

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

مقدمه

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

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

توضیحات

bank_code (اجباری): کد بانک که از جدول زیر قابل دسترسی است.

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

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

mobile (اجباری): شماره موبایل کاربر token دریافتی در این قسمت یکبار مصرف است و پس از ۲۰ دقیقه باطل می شود.

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

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

نمونه json

{
  "bank_code": "062",
  "mobile": "09123456789",
  "callback_url": "https://paperpiano.ir/subscription/callback",
  "count": 7,
  "limit": 10000,
  "name": "محمد مقصودی",
  "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

token: توکنی که با استفاده از آن تلاش کرده‌اید تا به صفحه‌ی بانک منتقل شوید.

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

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

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",
      "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": "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",
      "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": "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	string	required
withdrawal_date	string	required
is_instant	boolean	optional
notify_url	string	optional
max_retry_count	integer	optional

توضیحات

authorization_id (اجباری): آیدی دریافتی در بخش اشتراک که می خواهید مبلغ از آن دسترسی برداشت شود
amount (اجباری): مبلغ برداشت وجه
withdrawal_date (اجباری): تاریخی از امروز به بعد که می خواهید مبلغ در آن روز از حساب برداشت شود
is_instant (اختیاری): این پارامتر مشخص می‌کند که برداشت وجه در همین لحظه انجام شود یا در سیکل‌های مشخصی که توسط وندار کنترل می‌شوند. در صورت عدم ارسال، true در نظر گرفته می‌شود.
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 تبدیل می‌شود.

نمونه json

{
  "authorization_id": "9f307e30-dc77-11ea-830e-7533ca1787c5",
  "amount": "10000",
  "withdrawal_date": "2020-07-04",
  "is_instant": true,
  "notify_url": "http://yourdomain.com/notify/me",
  "max_retry_count": 1
}

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

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
    }
  }
}

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 تبدیل می‌شود.

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

اگر بیشتر از تعداد 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
    },
    ...
  ],
  "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 تبدیل می‌شود.
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
      }
    },
  }
}

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 تبدیل می‌شود.

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

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