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

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

معرفی سرویس

سرویس «پرداخت با وندار» با هدف توانمندسازی کسب‌وکارها در زمینه پرداخت مشتریان‌شان ایجاد شده است. این توانمندسازی دو بخش را شامل می‌شود: کسب‌وکارها و مشتریان کسب‌وکارها.

بخش کسب‌وکارها

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

درگاه پرداخت
پرداخت با یک کلیک
پرداخت اعتباری BNPL (Buy Now, Pay Later)
پرداخت خودکار (Direct Debit)
پرداخت اعتباری اقساطی

کافیست که کسب‌وکار فقط یک بار سرویس «پرداخت با وندار» را پیاده‌سازی کرده تا مشتریان بتوانند از تمام روش‌های پرداختی (به انتخاب کسب‌وکار) بهره‌مند شوند. از مزایای این نوع پیاده‌سازی می‌توان به موارد زیر اشاره کرد:

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

بخش مشتریان کسب‌وکار

مشتریان می‌توانند دسترسی‌های لازم روی حساب‌های بانکی و اعتباری خود را یک بار به وندار اعطا کنند تا وندار وظیفه احراز هویت و مراوده مالی تراکنش‌های مشتری را با تأمین‌کننده مالی و اعتباری (بانک یا سرویس‌های اعتباری) انجام دهد. از مزیت‌های سرویس «پرداخت با وندار» برای مشتریان به موارد زیر می‌توان اشاره کرد:

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

مقدمه

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

جهت سهولت پیاده‌سازی و کاهش پیچیدگی سیستم، سعی بر آن بوده است که این سرویس مشابه تجربه کاربری کسب‌وکارها در پیاده‌سازی سرویس IPG باشد. به این ترتیب فرآیندهای اصلی که سمت کسب‌وکار پیاده‌سازی خواهد شد، شامل چهار مرحله‌ی دریافت توکن، انتقال کاربر، استعلام و تأیید صورتحساب خواهد بود.

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

دریافت توکن

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

METHOD: post
URL: https://api.vandar.io/pbv/v1/send

پارامترهای هدر (Header) درخواست

Name	Type	Status
x-api-key	String	required

پارامترهای بدنه (Body) درخواست

Name	Type	Status
amount	Integer	required
callback_url	String	required
mobile	String	optional
national_code	String	optional
checkout_number	String	optional
description	String	optional

توضیحات

x-api-key (اجباری): این کلید از طریق پشتیبانی وندار در اختیار شما قرار می‌گیرد
amount (اجباری): مبلغ صورتحساب به صورت ریالی و بزرگتر یا مساوی 10000
callback_url (اجباری): باید با دامنه ثبت شده در وندار مطابقت داشته باشد
mobile (اختیاری): شماره موبایل کاربر سرویس شما
national_code (اختیاری): کدملی کاربر سرویس شما
checkout_number (اختیاری): شماره صورتحساب سرویس شما که رشته‌ای از اعداد به طول حداقل ۱ و حداکثر ۳۲ کاراکتر می‌تواند باشد
description (اختیاری): توضیحات (حداکثر 255 کاراکتر)

نمونه json

{
    "amount": 10000,
    "callback_url": "https://example.com/callback",
    "mobile": "09123456789",
    "national_code": "0123456789",
    "checkout_number": "12345",
    "description": "توضیحات دلخواه",
}

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

HTTP/1.1 200
{
    "message": "درخواست توکن با موفقیت ثبت شد",
    "data": {
        "token": "c78862c4-429e-448d-b57e-1f35e3126600"
    }
}

message: متن پاسخ
data: یک مجموعه از کلیدها و مقادیر آنها که در این سرویس کلید token می‌باشد

نکته! توکن دریافتی تا ۲۰ دقیقه قابل استفاده می‌باشد و پس از این زمان خطای 404 دریافت می‌کنید.

نکته! توکن دریافتی به منزله شناسه یکتای صورتحساب می‌باشد و در کلیه سرویس‌ها در پارامتر checkout_id باید ارسال شود.

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

HTTP/1.1 422
{
    "message": "اطلاعات وارد شده نامعتبر است",
    "code": "validation_error",
    "errors": {
        "amount": "فیلد مبلغ الزامی است.",
        "callback_url": "فیلد آدرس بازگشتی الزامی است."
    }
}
HTTP/1.1 403
{
    "message": "اپلیکیشن مربوط به درخواست شما فعال نیست",
    "code": "forbidden_error"
}

message: متن خطا
code: کد خطا
errors: یک مجموعه از کلیدها و مقادیر خطاهای دریافتی

انتقال کاربر

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

METHOD: get
URL: https://pbv.vandar.io/checkouts/{checkout_id}

نکته! پس از انجام فرآیند پرداخت توسط کاربر آدرس بازگشتی شما فراخوانی خواهد شد، پارامتر checkout_id و status به انتهای آدرس بازگشتی اضافه شده است. اگر مقدار پارامتر status برابر با SUCCEED بود، جهت تایید تراکنش باید سرویس تایید صورتحساب فراخوانی شود. در صورتیکه به اطلاعاتی از صورتحساب نیاز دارید می‌توانید سرویس استعلام را فراخوانی کنید تا از وضعیت صورتحساب مطمئن شوید. اما در نظر داشته باشید که فراخوانی این سرویس اجباری نیست و تنها جهت صحت‌سنجی اطلاعات تعریف شده است. در صورتیکه پرداخت کاربر با خطا مواجه شود مقدار status، برابر با FAILED خواهد بود.

استعلام

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

METHOD: get
URL: https://api.vandar.io/pbv/v1/checkouts/{checkout_id}

نکته! دریافت این اطلاعات به هیچ عنوان به معنی پرداخت صورتحساب نیست.

پارامترهای هدر (Header) درخواست

Name	Type	Status
x-api-key	String	required

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

HTTP/1.1 200
{
    "message": "مشخصات صورتحساب",
    "data": {
        "checkout": {
            "id": "c78862c4-429e-448d-b57e-1f35e3126600",
            "amount": "10000",
            "wage": "100",
            "status": "SUCCEED",
            "checkout_number": "12345",
            "description": "",
            "created_at": 1654378678
        }
    }
}

id: شناسه صورتحساب
amount: مبلغ صورتحساب که ممکن است با مبلغی که در مرحله اول ارسال کرده باشید متفاوت باشد. اگر کارمزد تراکنش بر عهده کاربر باشد. مبلغ کارمزد هم به مبلغ ارسالی از سمت شما اضافه شده است.
wage: مبلغ کارمزد
status: وضعیت صورتحساب که شامل وضعیت‌های زیر می‌باشد:

INIT: صورتحساب پردازش نشده است
SUCCEED: صورتحساب پرداخت و تایید شده است
PENDING_VERIFY: صورتحساب در انتظار تایید است
FAILED: صورتحساب ناموفق است

checkout_number: شماره صورتحساب سرویس شما
description: توضیحاتی که شما در مرحله اول ارسال کردید
created_at: تاریخ ایجاد صورتحساب

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

HTTP/1.1 4xx
{
    "message": "احراز هویت انجام نشده است",
    "code": "unauthenticated_error",
}

message: متن خطا
code: کد خطا

تایید

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

METHOD: post
URL: https://api.vandar.io/pbv/v1/verify

نکته!برای تایید صورتحساب ۲۰ دقیقه فرصت دارید و در صورتیکه در این زمان تایید نشود، صورتحساب ناموفق در نظر گرفته می‌شود

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

پارامترهای هدر (Header) درخواست

Name	Type	Status
x-api-key	String	required

پارامترهای بدنه (Body) درخواست

Name	Type	Status
checkout_id	String	required

توضیحات

x-api-key (اجباری): این کلید از طریق پشتیبانی وندار در اختیار شما قرار می‌گیرد
checkout_id (اجباری): شناسه صورتحساب

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

HTTP/1.1 200
{
    "message": "صورتحساب با موفقیت تایید شد"
}

message: متن خطا

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

HTTP/1.1 4xx
{
    "message": "امکان تایید این صورتحساب وجود ندارد",
    "code": "checkout_can_not_be_verified",
}

message: متن خطا
code: کد خطا