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

آخرین تغییرات: 1400/07/06

سرویس تسویه گروهی

مقدمه

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

لیست تسویه های گروهی ثبت شده

در این بخش شما می‌توانید لیست تسویه‌های گروهی را که تا به حال ثبت کرده‌اید، مشاهده نمایید.

METHOD: GET
URL: https://batch.vandar.io/api/v2/business/{business}/batches

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

page(اختیاری): صفحه مورد نظر را مشخص می‌کند.

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

HTTP/1.1 200
{
  "data": [
    {
      "batch_id": "900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
      "status": {
        "total_count": 1,
        "init_count": 0,
        "submitted_count": 1,
        "failed_count": 0
      },
      "total_amount": 50000,
      "created_at": 1629672276
    }
  ],
  "links": {
    "first": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches?page=1",
    "last": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
data:
- batch_id: شناسه تسویه گروهی ثبت شده
- status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.
- total_amount: مبلغ کلی تسویه های گروهی
- created_at: تاریخ ایجاد تسویه گروهی (timestamp)
- links:
  - first: آدرس اولین صفحه
  - last: آدرس آخرین صفحه
  - prev: آدرس صفحه قبل
  - next: آدرس صفحه بعد
- meta:
  - current_page: آدرس همین صفحه
  - from: شماره اولین آیتم تسویه ای که در این صفحه آمده است
  - last_page: تعداد کل صفحات تسویه
  - path: آدرس خالص بدون صفحه بندی
  - per_page: تعداد آیتم در هر صفحه
  - to: شماره آخرین آیتم تسویه ای که در این صفحه آمده است
  - total: تعداد کل آیتم های تسویه

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

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

جزییات یک تسویه گروهی

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

METHOD: GET
URL: https://batch.vandar.io/api/v2/business/{business}/batch-settlements/{batch_id}?per_page=20&page=1&status=SUBMITTED

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

پارامتر {batch_id} شناسه تسویه گروهی که در ثبت آن ارسال کرده اید.

per_page(اختیاری): تعداد رکورد اطلاعاتی درخواست تسویه را مشخص میکند

INIT: در حال ارسال
SUBMITTED: ارسال شده
FAILED: ناموفق

status(اختیاری): یکی از پارامتر های زیر را قبول می کند. و مشخص می کند چه نوع تسویه هایی در لیست جزییات تسویه گروهی نمایش داده شود. عدم ارسال این پارامتر باعث می شود تمام وضعیت ها در پاسخ نمایش داده شود.

page(اختیاری): صفحه مورد نظر را مشخص می‌کند.

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

HTTP/1.1 200
{
  "data": [
    {
      "id": "8736c960-039a-11ec-8171-334dd8b08284",
      "track_id": "d18ca2e8-4204-11ec-81d3-0242ac130003",
      "payment_number": "2",
      "amount": "50000",
      "iban": "IR150620000000203214109001",
      "status": "SUBMITTED",
      "type": "A2A",
      "transaction_id": 162967221235,
      "error_message": null,
      "description": null
    }
  ],
  "links": {
    "first": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640?page=1",
    "last": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
data:
- id: شناسه تسویه
- track_id: شناسه یکتای ارسالی
- payment_number: شناسه پرداخت ارسالی
- amount: مبلغ
- iban: شماره شبا
- status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.
- links:
  - INIT: در حال ارسال
  - SUBMITTED: ارسال شده
  - FAILED: ناموفق
- type: نوع تسویه (ACH - A2A).
- transaction_id: شناسه یکتای ونداری
- error_message: در صورت وضعیت خطا متن خطا در این پارامتر بر می گردد.
- description: در صورت ارسال توضیحات در هنگام ثبت تسویه گروهی این پارامتر بر میگردد.
- links:
  - first: آدرس اولین صفحه
  - last: آدرس آخرین صفحه
  - prev: آدرس صفحه قبل
  - next: آدرس صفحه بعد
- meta:
  - current_page: آدرس همین صفحه
  - from: شماره اولین آیتم تسویه ای که در این صفحه آمده است
  - last_page: تعداد کل صفحات تسویه
  - path: آدرس خالص بدون صفحه بندی
  - per_page: تعداد آیتم در هر صفحه
  - to: شماره آخرین آیتم تسویه ای که در این صفحه آمده است
  - total: تعداد کل آیتم های تسویه

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

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

ثبت درخواست تسویه گروهی

در این بخش شما می‌توانید یک درخواست تسویه گروهی را ثبت نمایید.

METHOD: POST
URL: https://batch.vandar.io/api/v2/business/{business}/batches-settlement

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

HTTP/1.1
{
  "batch_id": "e94cf0682d8721dee87c9e50544a17c079a0efe1e9a2514d410a49883c82180c9967bfe9ca2afdc2fba60d57e42b87c630c3f9f73eb3edb1aaf3438b4bfe7d6f",
  "batches_settlement": [
    {
      "track_id": "c612c886-7215-416c-bb55-2cefcde40e7d",
      "iban": "IR350700001000116383322001",
      "amount": 50000,
      "type": "A2A",
      "payment_number": 1,
      "description": "test"
    }
  ]
}

status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
batch_id: شناسه یکتایی که برای ثبت هر تسویه گروهی ارسال می گردد. این مقدار از512 Hash اطلاعات آرایه ارسالی batches_settlement ایجاد می شود. نمونه از ساخت این مقدار را می توانید در نمونه کد زیر که به زبان php است مشاهده کنید.
```
hash('sha512', json_encode([
    {
      "track_id": "c612c886-7215-416c-bb55-2cefcde40e7d",
      "iban": "IR350700001000116383322001",
      "amount": 50000,
      "type": "A2A",
      "payment_number": 1,
      "description": "test"
    }
  ])
                            
```
batches_settlement: لیستی از تسویه ها که همزمان ارسال می شوند.
- amount (اجباری): مبلغ تراکنش به ریال و بزرگتر یا مساوی 50,000 و کوچکتر یا مساوی 500,000,000
- iban (اجباری): شماره شبا ای که می خواد پول به آن واریز شود
- track_id (اجباری): رشته پیگیری که به ازای هر درخواست تسویه بایستی یکتا باشد. پیشنهاد ما استفاده از uuid برای این پارامتر است. این پارامتر به حروف بزرگ و کوچک حساس است.
- type (اختیاری): اگر میخواهید تسویه خود به صورت حساب به حساب انجام شود، A2A و در غیراینصورت مقدار ACH را میتوانید ارسال کنید.
- payment_number (اختیاری): شناسه واریز شماره ای اختیاری است.
- description (اختیاری): توضیحات تا حداکثر 256 کاراکتر اختیاری است.

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

HTTP/1.1 200
{
      "batch_id": "900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
      "status": {
        "total_count": 1,
        "init_count": 0,
        "submitted_count": 1,
        "failed_count": 0
      },
      "total_amount": 50000,
      "created_at": 1629672276
}

با ثبت موقث تسویه گروهی خورجی بالا با جزییات زیر نمایش داده می شود.

batch_id: شناسه تسویه گروهی ثبت شده
status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.

total_count: تعداد کل تسویه گروهی ثبت شده
init_count: تعداد تسویه هایی که در حال ارسال هستند
submitted_count: تعداد تسویه هایی که ارسال شده اند
failed_count: تعداد تسویه هایی که با خطا مواجه شده اند

total_amount: مبلغ کلی تسویه های گروهی
created_at: تاریخ ایجاد تسویه گروهی (timestamp)

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

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