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

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

مقدمه

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

پرداخت یکپارچه سرویس پرداختی است که تمام روش های پرداخت (پرداخت از حساب، پرداخت با کارت، پرداخت اعتباری، کیف پول و ...) را بصورت یکپارچه و جامع به کسب و کار های ارايه میکند. در این سرویس با اضافه شدن روش های پرداخت جدید نیازی به پیاده سازی جدیدی نخواهید داشت.

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

Accept: application/json
x-api-key: {api-key}

آبجکت های سرویس پرداخت یکپارچه

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

۱. آبجکت مشتری (customer)

{
    "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
    "mobile": "09354614194",
    "first_name": "Ali",
    "last_name": "Gholami",
    "national_code": "0123456789",
    "email": "asd@qwe.com"
}

id: شناسه مشتری.
mobile: شماره موبایل مشتری.
first_name: نام مشتری.
last_name: نام خانوادگی مشتری.
national_code: کدملی مشتری.
email: : ایمیل مشتری.

۲. آبجکت مجوز پرداخت از حساب (mandate)

{
    "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
    "payment_method": "debit-saman",
    "count": 30,
    "limit": 30000000,
    "expires_at": 1685350749,
    "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
    "status": "active",
    "created_at": 1662452234,
    "updated_at": 1662452234,
    "revoked_at": null
}

id: شناسه مجوز پرداخت از حساب.
payment_method: روش پرداخت.
count: حداکثر تعداد دفعاتی که در یک ماه می‌توان با این مجوز، پرداخت موفق انجام داد.
limit: حداکثر مبلغ قابل برداشت در پرداخت وجه‌های مربوط به این مجوز. واحد پول ریال است.
expires_at: تاریخ انقضای مجوز.
customer_id: شناسه مشتری.
status: وضعیت مجوز.
created_at: زمان ایجاد مجوز.
updated_at: زمان بروزرسانی مجوز.
revoked_at: زمان لغو مجوز.

۳. آبجکت پرداخت (payment)

{
    "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
    "payment_method": "debit-ayandeh",
    "amount": 10000,
    "wage_amount": 1000,
    "affected_amount": 9000,
    "ref_id": null,
    "tracking_code": null,
    "status": "done",
    "error": null,
    "created_at": 1673773548,
    "updated_at": 1673773548,
    "paid_at": 1673773548,
    "type": "debit",
    "debit": {
        "mandate_id": "068bb9f0-5ddf-11ed-b16d-61da2281b3d4"
    }
}

id: شناسه پرداخت.
payment_method: روش پرداخت.
amount: مبلغ پرداخت.
wage_amount: کارمزد پرداخت.
affected_amount: مبلغی که کیف پول کسب و کار را تحت تاثیر قرار داده است.
ref_id: رسید دیجیتال یکتا در شبکه پرداخت کشور.
tracking_code: کد رهگیری به همراه تاریخ انجام تراکنش یکتا است.
status: وضعیت پرداخت.
error: خطا در صورت انجام نشدن پرداخت.

نکته! در صورت وجود خطا فیلد error مشابه زیر خواهد بود:

"error": {
   "code": "WITHDRAWAL_TIMEOUT",
   "message": "withdrawal timeout"
}

created_at: زمان ایجاد پرداخت.
updated_at: زمان بروزرسانی پرداخت.
paid_at: زمان انجام تراکنش.
type: نوع روش پرداختی که در حال حاضر از مقادیر debit، credit و card پشتیبانی می شود.
debit.mandate_id: درصورتی که نوع روش پرداختی برابر debit باشد شناسه مجوز پرداخت از حساب برگردانده میشود.
credit: در صورتی که نوع روش پرداختی برابر با credit باشد، این پارامتر نمایش داده می شود که در حال حاضر مقدار آن برابر null است.
card: در صورتی که نوع روش پرداخت برابر با card باشد دو مقدار cid و card_number برای شما بازگردانده می شود.
card.card_number: شماره کارت پرداخت کننده.
card.cid: هش شماره کارت که با الگوریتم SHA256 هش شده است.

۴. آبجکت صورت‌حساب (checkout)

{
    "id": "fbcf27ba-45d2-4aee-aa50-18a7d33a5d27",
    "request_id": "sDrfgkT5lkk5llk4Gt",
    "checkout_number": "123",
    "amount": 10000,
    "status": "paid",
    "description": "test",
    "created_at": 1673773548,
    "updated_at": 1673773548,
    "customer": {
        "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
        "mobile": "09354614194",
        "first_name": "Ali",
        "last_name": "Gholami",
        "national_code": "0123456789",
        "email": "asd@qwe.com"
    },
    "payments": [
        {
            "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
            "payment_method": "debit-ayandeh",
            "amount": 10000,
            "wage_amount": 1000,
            "affected_amount": 9000,
            "ref_id": null,
            "tracking_code": null,
            "status": "done",
            "error": null,
            "created_at": 1673773548,
            "updated_at": 1673773548,
            "paid_at": 1673773548,
            "type": "debit",
            "debit": {
                "mandate_id": "068bb9f0-5ddf-11ed-b16d-61da2281b3d4"
            }
        }
    ]
}

id: شناسه صورت‌حساب
request_id: شناسه یکتا صورت‌حساب
checkout_number: شماره فاکتور صورت‌حساب
amount: مبلغ صورت‌حساب
status: وضعیت صورت‌حساب
description: توضیحات صورت‌حساب
updated_at: زمان بروزرسانی صورت‌حساب
customer: اطلاعات مشتری
payments: اطلاعات پرداخت

مدیریت روش‌های پرداخت

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

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

۱. فعال‌ و غیرفعال‌سازی روش‌های پرداخت

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

برای این کار کافی است که از داشبورد وارد کسب و کار مورد نظر خود شوید و از منوی سمت راست بر روی پرداخت یکپارچه کلیک نمایید.

فعال یا غیر فعال‌سازی روش‌های پرداخت

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

فعال یا غیر فعال‌سازی روش‌های پرداخت

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

فعال یا غیر فعال‌سازی روش‌های پرداخت

۲. دریافت لیست روش‌های پرداخت

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

Method:  GET
Address: https://api.vandar.io/mpg/v1/business/{business}/payment-methods

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

پارامترهای مجاز

name	Type	Status
mobile	string	optional
modes	array	optional
types	array	optional
limit	numeric	optional
is_healthy	boolean	optional

توضیحات

mobile (اختیاری): شماره موبایل کاربر. شماره موبایل بدون کد کشور و به فرمت 09123456789 باشد.

نکته! اگر موبایل در درخواست مربوطه ارسال گردد، و روش پرداخت از نوع debit باشد، لیست مجوز پرداخت از حسابهای فعال مربوط به آن شماره موبایل نیز در پاسخ دریافتی قرارخواهد گرفت.(در نمونه پاسخ دریافتی میتوانید مشاهده کنید.)

modes (اختیاری): این کلید به مدل پرداخت مربوط است. هر مقداری وارد شود، بر اساس مقدار وارد شده لیست روش های پرداخت فیلتر می‌شود.

نکته! در حال حاضر این سرویس از یک مدل پرداخت پشتیبانی میکند:

once : جهت پرداخت یک باره

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

نکته! در حال حاضر این سرویس سه مدل پرداخت را پشتیبانی میکند:

debit : پرداخت از حساب
credit : پرداخت اعتباری
card : پرداخت با کارت

limit (اختیاری): هر روش پرداختی محدودیت سقف برداشت دارد. درصورت وارد کردن این کلید، روش‌های پرداخت بر اساس حداقل مقدار وارد شده فیلتر می‌شود.
is_healthy (اختیاری): هر روش پرداختی بنابر دلایل مختلف ممکن است به صورت موقت آماده به ارائه خدمات نباشد. درصورت وارد کردن این کلید ، روش‌های پرداخت بر اساس مقدار وارد شده فیلتر می‌شود.

نمونه json

{
    "mobile": "09354614194",
    "modes": [
        "once"
    ],
    "types": [
        "debit"
    ],
    "limit": 3000000,
    "is_healthy": true
}

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

HTTP/1.1 200
{
    "message": "لیست متد های پرداخت."
    "data": [
        {
            "modes": [
                   "once"
            ],
            "slug": "debit-saman",
            "type": "debit",
            "name": "بانک سامان",
            "logo": "https://cdn.vandar.io/mpg/payment_methods/debit-saman.svg",
            "is_healthy": true,
            "limit": 4270045,
            "debit": {
                "mandates": [
                    {
                        "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
                        "payment_method": "debit-saman",
                        "count": 30,
                        "limit": 30000000,
                        "expires_at": 1685350749,
                        "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                        "status": "active",
                        "created_at": 1662452234,
                        "updated_at": 1662452234,
                        "revoked_at": null
                    }
                ]
            }
        }
    ]
}

صدور مجوز در روش پرداخت از حساب

۱. درخواست بستن مجوز پرداخت از حساب:

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

Method: POST
Address: https://api.vandar.io/mpg/v1/business/{business}/mandates

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

پارامترهای مجاز

name	Type	Status
payment_method	string	required
count	integer	required
limit	integer	required
expires_at	UNIX timestamp	required
callback_url	string	required
customer.mobile	string	required
customer.first_name	string	optional
customer.last_name	string	optional
customer.national_code	string	optional
customer.email	string	optional

توضیحات

payment_method: (اجباری) slug روش‌ پرداخت که از لیست روش های پرداخت قابل استفاده است.
count (اجباری): حداکثر تعداد دفعاتی که در یک ماه می‌توان با این مجوز پرداخت از حساب، برداشت وجه موفق انجام داد.
limit (اجباری): حداکثر مبلغ وجه قابل برداشت در هر درخواست مربوط به این مجوز پرداخت از حساب. واحد پول ریال است.
expires_at: (اجباری) تاریخ انقضای مجوز پرداخت از حساب. این تاریخ باید بزرگتر از تاریخ روز جاری باشد و به صورت UNIX timestamp وارد می‌شود.
callback_url (اجباری): آدرس بازگشتی که کاربر پس از تایید اطلاعات در صفحه بانک، به آن منتقل می‌شود.
customer:
- mobile (اجباری): شماره موبایل کاربر. شماره موبایل بدون کد کشور و به فرمت 09123456789 باشد.
- first_name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
- last_name (اختیاری): نام‌خانوادگی کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
- national_code (اختیاری): کدملی کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.
- email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.

نمونه json

{
  "payment_method": "debit-saman",
  "count": 7,
  "limit": 10000,
  "expires_at": 1685350749,
  "callback_url": "https://paperpiano.ir/mandate/callback",
  "customer": {
    "mobile": "09123456789",
    "first_name": "محمد",
    "last_name": "مقصودی",
    "national_code": "0123456789",
    "email": "yourcustomer@gmail.com",
  }
}

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

HTTP/1.1 200
{
  "message": "درخواست توکن با موفقیت ثبت شد.",
  "data": {
      "token": "0cf235d0-d48b-11ea-86cd-298ec898a9bd",
      "customer": {
            "mobile": "09123456789",
            "first_name": "محمد",
            "last_name": "مقصودی",
            "national_code": "0098001212",
            "email": "yourcustomer@gmail.com",
      }
    }
  }
}

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

message: پیغام درخواست توکن با موفقیت ثبت شد.
data:
- token: از این توکن برای انتقال کاربر به صفحه بانک و گرفتن دسترسی مجوز پرداخت از حساب استفاده خواهد شد.
- customer:
  - mobile: شماره موبایل کاربر
  - first_name: نام کاربر
  - last_name: نام‌خانوادگی کاربر
  - national_code: کدملی کاربر
  - email: ایمیل کاربر

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

در مرحله بعد token دریافتی از قسمت قبل را در انتهای آدرس می گذارید و در مرورگر وارد سایت می شوید.

METHOD: get
URL: https://mpg.vandar.io/mandates/{token}

در صورتی که در ارتباط با روش‌های پرداخت اختلال پیش آمده باشد شما با آدرس زیر روبرو می‌شوید:

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&status=FAILED_TO_ACCESS_BANK

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

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

صفحه ورود روش‌های پرداخت

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

صفحه دسترسی

۳. دریافت کد مجوز پرداخت از حساب

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

در صورت اجازه‌ی دسترسی به حساب در صفحه‌ی روش‌های پرداخت

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&mandate_id=9f307e30-dc77-11ea-830e-7533ca1787c5&status=SUCCEED

در صورت عدم اجازه‌ی دسترسی به حساب در صفحه‌ی روش‌های پرداخت

https://yourdomain.com/callback?token=0cf235d0-d48b-11ea-86cd-298ec898a9bd&status=FAILED&error_code=user_declined_to_confirm_mandate

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

error_code	error_message

۴. تایید مجوز پرداخت از حساب

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

Method: PATCH
Address: https://api.vandar.io/mpg/v1/business/{business}/mandates/{mandate_id}

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

نکته! وندار به جهت جلوگیری از ایجاد مجوز پرداخت از حساب رهاشده، مجوز پرداخت از حسابهایی که پس از ۲۰ دقیقه تایید نشوند را به شکل خودکار لغو می‌کند.

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

HTTP/1.1 200
{
    "message": "مجوز پرداخت از حساب با موفقیت تایید شد",
    "data": {
        "mandate": {
            "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
            "payment_method": "debit-saman",
            "count": 30,
            "limit": 30000000,
            "expires_at": 1685350749,
            "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
            "status": "active",
            "created_at": 1662452234,
            "updated_at": 1662452234,
            "revoked_at": null
        }
    }
}

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

HTTP/1.1 403
{
    "message": "مجاز به انجام این کار نیستید",
    "code": "mandate_already_revoked"
}

HTTP/1.1 403
{
    "message": "مجاز به انجام این کار نیستید",
    "code": "mandate_already_activated"
}

۵. لیست مجوز پرداخت از حسابها

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

METHOD: GET
URL: https://api.vandar.io/mpg/v1/business/{business}/mandates

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

پارامترهای مجاز

name	Type	Status
page	numeric	optional
per_page	numeric	optional

page (اختیاری): شماره صفحه.
per_page (اختیاری): تعداد آیتم در هر صفحه.

نمونه json

{
    "page": 1,
    "per_page":12
}

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

HTTP/1.1 200
{
    "message": "لیست مجوزهای پرداخت از حساب کسب و کار",
    "data": [
        {
             "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
             "payment_method": "debit-saman",
             "count": 30,
             "limit": 30000000,
             "expires_at": 1685350749,
             "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
             "status": "active",
             "created_at": 1662452234,
             "updated_at": 1662452234,
             "revoked_at": null
        },
        {
             "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
             "payment_method": "debit-saman",
             "count": 30,
             "limit": 30000000,
             "expires_at": 1685350749,
             "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
             "status": "active",
             "created_at": 1662452234,
             "updated_at": 1662452234,
             "revoked_at": null
        },
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "links": [
            ...
        ],
        "path": "https://api.vandar.io/mpg/v1/business/{business}/mandates",
        "per_page": 50,
        "to": 50,
        "total": 75
    },
}

data:
- id: شناسه مجوز پرداخت از حساب که برای درخواست برداشت وجه از این شناسه استفاده می شود.
- count: تعداد درخواست های برداشت وجه که به صورت ماهانه مشخص می‌شود.
- limit: حداکثر مبلغ برداشت وجه در هر برداشت. واحد پول ریال است.
- payment_method: روش‌ پرداخت که به لیست آن در بالا اشاره شده است.
- status: وضعیت مجوز.
- expires_at: تاریخ انقضای مجوز.
- customer_id: شناسه مشتری مربوط به این مجوز.
- created_at: تاریخ ایجاد مجوز.
- updated_at: تاریخ آخرین بروزرسانی مجوز.
- revoked_at: تاریخ لغو مجوز.
meta:
- current_page: آدرس همین صفحه
- from: شماره اولین آیتم که در این صفحه آمده است
- last_page: تعداد کل صفحات
- per_page: تعداد آیتم در هر صفحه
- to: شماره آخرین آیتمی که در این صفحه آمده است
- total: تعداد کل آیتم ها

نکته! در این قسمت در خروجی id را دریافت میکنیم که در مراحل بعد برای استفاده از متد show و revoke و verify که برای نمایش و پاک کردن و تایید مجوز پرداخت از حساب است مورد استفاده قرار میگیرد.

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

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

message: پیغام خطا
code: کد خطا

۶. نمایش یک مجوز پرداخت از حساب با id

شما می توانید با این دستور جزییات یک مجوز پرداخت از حساب را با فرستادن id دریافت کنید.

Method: GET
Address: https://api.vandar.io/mpg/v1/business/{business}/mandates/{id}

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

پارامتر {id} همان شناسه مجوز پرداخت از حساب مربوطه است.

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

HTTP/1.1 200
{
    "message": "مجوز پرداخت از حساب کسب و کار",
    "data": {
        "mandate": {
            "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
             "payment_method": "debit-saman",
             "count": 30,
             "limit": 30000000,
             "expires_at": 1685350749,
             "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
             "status": "active",
             "created_at": 1662452234,
             "updated_at": 1662452234,
             "revoked_at": null
        }
    }
}

۷. لغو مجوز پرداخت از حساب با استفاده از id

Method: DELETE
Address: https://api.vandar.io/mpg/v1/business/{business}/mandates/{id}

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

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

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

HTTP/1.1 200
{
  "status": 1,
  "message": "مجوز پرداخت از حساب کسب و کار با موفقیت لغو شد.",
  "data": {
    "mandate": {
          "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
          "payment_method": "debit-saman",
          "count": 30,
          "limit": 30000000,
          "expires_at": 1685350749,
          "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
          "status": "active",
          "created_at": 1662452234,
          "updated_at": 1662452234,
          "revoked_at": 1662452234
    }
  }
}

message: پیغام مجوز پرداخت از حساب کسب و کار با موفقیت لغو شد.
data:
- mandate:
  - id: آیدی مجوز پرداخت از حساب حذف شده
  - count: حداکثر تعداد دفعاتی که در یک ماه می‌ شد با مجوز پرداخت از حساب حذف شده برداشت انجام شود.
  - limit: حداکثر مبلغ وجه قابل برداشت با مجوز پرداخت از حساب حذف شده.
  - payment_method: slug روش‌ پرداخت
  - status: وضعیت مجوز پرداخت از حساب
  - expires_at: تاریخ انقضای مجوز پرداخت از حساب
  - callback_url: آدرس بازگشتی درگاه پرداخت تایید شده در وندار
  - customer_id: آیدی کاربری که مجوز پرداخت از حساب برای او صادر شده بود.
  - created_at: تاریخ ایجاد به صورت timestamp
  - updated_at: تاریخ آخرین بروزرسانی به صورت timestamp
  - revoked_at: تاریخ حذف به صورت timestamp

نکته! بعد از لغو یک مجوز پرداخت از حساب این مجوز پرداخت از حساب از خروجی لیست مجوز پرداخت از حسابها حذف شده و اگر درخواست نمایش مجوز پرداخت از حساب با آیدی را صدا بزنید خطای ۴۲۲ با متن مجوز پرداخت از حساب باطل شده است را دریافت می کنید.

سرویس صورت‌حساب (Checkout)

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

۱. ثبت صورت‌حساب

Method: POST
Address: https://api.vandar.io/mpg/v1/business/{business}/checkouts

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

پارامترهای مجاز

name	Type	Status
payment_method	string	required
amount	numeric	required
request_id	string	optional
checkout_number	string	optional
description	string	optional
type	string	required, can be [debit, credit, card]

توضیحات

payment_method (اجباری): روش پرداختی
amount (اجباری): مبلغ صورت‌حساب
request_id (اختیاری): برای جلوگیری از تکراری بودن درخواست(یکتا برای هر درخواست).
checkout_number (اختیاری): شماره فاکتور
description (اختیاری): توضیحات اختیاری
type (اجباری): نوع روش پرداختی که در حال حاضر از مقادیر debit، credit و card پشتیبانی می شود.

با توجه به نوع روش پرداختی (debit، credit و card) نیاز هست که شما پارامترهای دیگری نیز ارسال نمایید.

پارامترهای اضافی مورد نیاز زمانی که type برابر با debit است.

name	Type	Status
debit	object	required if type = debit
debit.mandate_id	string	required if type = debit

توضیحات

mandate_id (اجباری): شناسه مجوز پرداخت از حساب.

نمونه json

{
    "payment_method": "debit-ayandeh",
    "amount": 1000,
    "request_id": 123,
    "checkout_number": "123",
    "description": "test",
    "type": "debit",
    "debit": {
        "mandate_id": "2de1307d-26e2-4de7-81c0-610c86a404cd"
    }
}

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

HTTP/1.1 200
{
    "message": "صورت‌حساب با موفقیت ثبت شد",
    "data": {
        "checkout": {
            "id": "fbcf27ba-45d2-4aee-aa50-18a7d33a5d27",
            "request_id": "sDrfgkT5lkk5llk4Gt",
            "checkout_number": "123",
            "amount": 10000,
            "status": "paid",
            "description": "test",
            "created_at": 1673773548,
            "updated_at": 1673773548,
            "customer": {
                "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                "mobile": "09354614194",
                "first_name": "Ali",
                "last_name": "Gholami",
                "national_code": "0123456789",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                     "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                     "payment_method": "debit-ayandeh",
                     "amount": 10000,
                     "wage_amount": 1000,
                     "affected_amount": 9000,
                     "ref_id": null,
                     "tracking_code": null,
                     "status": "done",
                     "error": null,
                     "created_at": 1673773548,
                     "updated_at": 1673773548,
                     "paid_at": 1673773548,
                     "type": "debit",
                     "debit": {
                         "mandate_id": "068bb9f0-5ddf-11ed-b16d-61da2281b3d4"
                     }
                }
            ]
        }
    }
}

message: پیغام ثبت صورت‌حساب
data:
- checkout: اطلاعات صورت‌حساب

پارامترهای اضافی مورد نیاز زمانی که type برابر با credit است.

name	Type	Status
credit	object	required if type = credit
credit.callback_url	string	required if type = credit
credit.customer	object	required if type = credit
credit.customer.mobile	string	required if type = credit
credit.customer.first_name	string	optional if type = credit
credit.customer.last_name	string	optional if type = credit
credit.customer.national_code	string	optional if type = credit
credit.customer.email	string	optional if type = credit

توضیحات

callback_url (اجباری): آدرس بازگشتی که کاربر پس از پرداخت، به آن منتقل می‌شود.

mobile (اجباری): شماره موبایل کاربر. شماره موبایل بدون کد کشور و به فرمت 09123456789 باشد.
first_name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
last_name (اختیاری): نام‌خانوادگی کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
national_code (اختیاری): کدملی کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.
email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.

نمونه json

{
    "payment_method": "credit-tara",
    "amount": 10000,
    "request_id": "67843357634568",
    "checkout_number": "123",
    "description": "test",
    "type": "credit",
    "credit": {
        "callback_url": "https://your-callback-address.com",
        "customer": {
            "mobile": "09367636320",
            "first_name": "Amirali",
            "last_name": "Habashizadeh",
            "national_code": "0123456789",
            "email": "asd@qwe.com",
        }
    }
}

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

HTTP/1.1 200
"message": "صورتحساب با موفقیت ثبت شد",
    "data": {
        "checkout": {
            "id": "5460fedc-3484-41d6-b4be-b8dcba1afc4d",
            "request_id": "67843357634568",
            "checkout_number": "123",
            "amount": 10000,
            "status": "not_paid",
            "description": "test",
            "created_at": 1678095461,
            "updated_at": 1678095461,
            "customer": {
                "id": "de49afb0-b80b-11ed-8f15-65e047110052",
                "mobile": "09367636320",
                "first_name": "Amirali",
                "last_name": "Habashizadeh",
                "national_code": "0123456789",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                        "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                        "payment_method": "credit-tara",
                        "amount": 10000,
                        "wage_amount": 1000,
                        "affected_amount": 9000,
                        "ref_id": null,
                        "tracking_code": null,
                        "status": "pending_redirect",
                        "error": null,
                        "created_at": 1673773548,
                        "updated_at": 1673773548,
                        "paid_at": 1673773548,
                        "type": "credit",
                        "credit": null
                }
            ]
        }
    }
}

پارامترهای اضافی مورد نیاز زمانی که type برابر با card است.

name	Type	Status
card	object	required if type = card
card.callback_url	string	required if type = card
card.valid_card_number	string	optional if type = card
card.customer	object	required if type = card
card.customer.mobile	string	required if type = card
card.customer.first_name	string	optional if type = card
card.customer.last_name	string	optional if type = card
card.customer.national_code	string	optional if type = card
card.customer.email	string	optional if type = card

توضیحات

callback_url (اجباری): آدرس بازگشتی که کاربر پس از پرداخت، به آن منتقل می‌شود.
valid_card_numbers (اختیاری): شماره کارت های معتبر (در صورت ارسال شماره کارت، کاربر فقط با همان شماره کارت قابلیت پرداخت خواهد داشت.)

mobile (اجباری): شماره موبایل کاربر. شماره موبایل بدون کد کشور و به فرمت 09123456789 باشد.
first_name (اختیاری): نام کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
last_name (اختیاری): نام‌خانوادگی کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود
national_code (اختیاری): کد ملی معتبر (در صورت ارسال کد ملی، کاربر فقط با کارت‌های بانکی تحت مالکیت آن کد ملی قابلیت پرداخت خواهد داشت. برای بررسی کدملی در درگاه پرداخت ارسال شماره موبایل مرتبط با کد ملی نیز الزامی است.)
email (اختیاری): ایمیل کاربر که بهتر است برای پیگیری‌های بعدی ارسال شود.

نمونه json

{
    "payment_method": "card-saman",
    "amount": 10000,
    "request_id": "67843357634567",
    "checkout_number": "123",
    "description": "test",
    "type": "card",
    "card": {
        "callback_url": "https://your-callback-address.com",
        "valid_card_number": "5859832060120699",
        "customer": {
            "mobile": "09367636320",
            "first_name": "Amirali",
            "last_name": "Habashizadeh",
            "national_code": "0058598310",
            "email": "asd@qwe.com",
        }
    }
}

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

HTTP/1.1 200
{
    "message": "صورت‌حساب با موفقیت ثبت شد",
    "data": {
        "checkout": {
            "id": "76e4e560-5ded-4953-80c7-d6324cc70954",
            "request_id": "67843357634567",
            "checkout_number": "123",
            "amount": 10000,
            "status": "not_paid",
            "description": "test",
            "created_at": 1678095120,
            "updated_at": 1678095120,
            "customer": {
                "id": "de49afb0-b80b-11ed-8f15-65e047110052",
                "mobile": "09367636320",
                "first_name": "Amirali",
                "last_name": "Habashizadeh",
                "national_code": "0058598310",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                    "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                    "payment_method": "card-saman",
                    "amount": 10000,
                    "wage_amount": 1000,
                    "affected_amount": 9000,
                    "ref_id": null,
                    "tracking_code": null,
                    "status": "pending_redirect",
                    "error": null,
                    "created_at": 1673773548,
                    "updated_at": 1673773548,
                    "paid_at": 1673773548,
                    "type": "card",
                    "card": null
                }
            ]
        }
    }
}

۲. انتقال کاربر

اگر type پرداختی شما از نوع های credit یا card باشد، نیاز هست که کاربر خود را پس از ثبت موفقیت آمیز صورتحساب به آدرس زیر منتقل نمایید تا فرآیند پرداخت تکمیل شود.

مقدار payment_id برابر است با id برگشتی در آبجکت payments که به صورت uuid می باشد.

Method: GET
Address: https://mpg.vandar.io/payments/{payment_id}/pay

نکته! بعد از این مرحله منتظر بمانید که کاربر از صفحه پرداخت بازگردد. بعد از بازگشت دو پارامتر status و payment_id به آنتهای آدرس بازگشتی به صورت query params اضافه شده است. مانند آدرس زیر

https://your-callback-address.com?payment_id=17f06477-ce51-488c-9cca-e51fcbb061f6&status=pending_verify

status می تواند دو مقدار pending_verify و failed داشته باشد. اگر مقدار برابر با failed بود، همینجا می‌توانید فرایند پرداخت را متوقف کنید. اما اگر مقدار آن برابر با pending_verify بود، باید بخش آخر یعنی تایید تراکنش را انجام دهید.

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

اگر type پرداختی شما از نوع های credit یا card باشد، نیاز هست که تراکنش کاربر خود را تایید نمایید.

Method: PATCH
Address: https://api.vandar.io/mpg/v1/business/{business}/payments/{payment_id}

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

پارامتر {payment_id} همان مقدار payment_id هست که قصد تایید آن تراکنش را دارید.

نمونه پاسخ دریافتی موفق زمانی که type برابر است با card:

HTTP/1.1 200
{
    "message": " صورتحساب با موفقیت پرداخت شد",
    "data": {
        "payment": {
            "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
            "payment_method": "card-saman",
            "amount": 10000,
            "wage_amount": 1000,
            "affected_amount": 9000,
            "ref_id": null,
            "tracking_code": null,
            "status": "pending_redirect",
            "error": null,
            "created_at": 1673773548,
            "updated_at": 1673773548,
            "paid_at": 1673773548,
            "type": "card",
            "card": {
                "card_number": "585983******0697",
                "cid": "70A40B00C479015F96B12AE465E2E5E51F57D172655EDADB539F97119132438B"
            }
        }
    }
}

نمونه پاسخ دریافتی موفق زمانی که type برابر است با credit:

HTTP/1.1 200
{
    "message": " صورتحساب با موفقیت پرداخت شد",
    "data": {
        "payment": {
            "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
            "payment_method": "card-saman",
            "amount": 10000,
            "wage_amount": 1000,
            "affected_amount": 9000,
            "ref_id": null,
            "tracking_code": null,
            "status": "pending_redirect",
            "error": null,
            "created_at": 1673773548,
            "updated_at": 1673773548,
            "paid_at": 1673773548,
            "type": "credit",
            "credit": null
        }
    }
}

۴. لیست صورت‌حساب

Method: GET
Address: https://api.vandar.io/mpg/v1/business/{business}/checkouts

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

پارامترهای مجاز

name	Type	Status
per_page	numeric	optional
page	numeric	optional

توضیحات

per_page (اختیاری): تعداد آیتم در هر صفحه
page (اختیاری): شماره صفحه

نمونه json

{
    "per_page": 2,
    "page": 1
}

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

HTTP/1.1 200
{
    "message": "لیست صورتحساب ها",
    "data": [
        {
            "id": "76252e83-fa00-46a4-b157-171213f2908a",
            "request_id": "123",
            "checkout_number": "123",
            "amount": "10000",
            "status": "paid",
            "description": "test",
            "created_at": 1673682519,
            "updated_at": 1673682519,
            "customer": {
                "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                "mobile": "09354614194",
                "first_name": "Ali",
                "last_name": "Gholami",
                "national_code": "0123456789",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                    "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                    "payment_method": "debit-ayandeh",
                    "amount": 10000,
                    "wage_amount": 1000,
                    "affected_amount": 9000,
                    "ref_id": null,
                    "tracking_code": null,
                    "status": "done",
                    "error": null,
                    "created_at": 1673773548,
                    "updated_at": 1673773548,
                    "paid_at": 1673773548,
                    "type": "debit",
                    "debit": {
                        "mandate_id": "068bb9f0-5ddf-11ed-b16d-61da2281b3d4"
                    }
                }
            ]
        },
        {
            "id": "206428c9-54ff-4f49-9abc-f3b7c8326d3c",
            "request_id": "456",
            "checkout_number": "123",
            "amount": "10000",
            "status": "not_paid",
            "description": "test",
            "created_at": 1673684560,
            "updated_at": 1673684560,
            "customer": {
                "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                "mobile": "09354614194",
                "first_name": "Ali",
                "last_name": "Gholami",
                "national_code": "0123456789",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                    "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                    "payment_method": "debit-ayandeh",
                    "amount": 10000,
                    "wage_amount": 1000,
                    "affected_amount": 9000,
                    "ref_id": null,
                    "tracking_code": null,
                    "status": "done",
                    "error": null,
                    "created_at": 1673773548,
                    "updated_at": 1673773548,
                    "paid_at": 1673773548,
                    "type": "debit",
                    "debit": {
                        "mandate_id": "068bb9f0-5ddf-11ed-b16d-61da2281b3d4"
                    }
                }
            ]
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 7,
        "links": [
            ...
        ],
        "path": "https://api.vandar.io/mpg/v1/business/{business}/checkouts",
        "per_page": 12,
        "to": 12,
        "total": 77
    }
}

message: پیغام لیست صورت‌حساب ها
data: لیستی از صورت‌حساب ها

۵. جزيیات صورت‌حساب

Method: GET
Address: https://api.vandar.io/mpg/v1/business/{business}/checkouts/76252e83-fa00-46a4-b157-171213f2908a

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

HTTP/1.1 200
{
    "message": "صورتحساب",
    "data": {
        "checkout": {
            "id": "76252e83-fa00-46a4-b157-171213f2908a",
            "request_id": "123",
            "checkout_number": "123",
            "amount": "10000",
            "status": "paid",
            "description": "test",
            "created_at": 1673682519,
            "updated_at": 1673682519,
            "customer": {
                "id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                "mobile": "09354614194",
                "first_name": "Ali",
                "last_name": "Gholami",
                "national_code": "4219849671",
                "email": "asd@qwe.com"
            },
            "payments": [
                {
                    "id": "b7d0d74c-4b25-4d42-8338-d9dce3c9e16f",
                    "payment_method": "debit-ayandeh",
                    "amount": 10000,
                    "wage_amount": 1000,
                    "affected_amount": 9000,
                    "ref_id": null,
                    "tracking_code": null,
                    "status": "done",
                    "error": null,
                    "created_at": 1673773548,
                    "updated_at": 1673773548,
                    "paid_at": 1673773548,
                    "type": "debit",
                    "debit": {
                        "mandate": {
                            "id": "1408bf10-2dcd-11ed-b084-bb5348c5e321",
                            "payment_method": "debit-saman",
                            "count": 30,
                            "limit": 30000000,
                            "expires_at": 1685350749,
                            "customer_id": "efdaf820-2075-11ed-a96b-a9167c05d45d",
                            "status": "active",
                            "created_at": 1662452234,
                            "updated_at": 1662452234,
                            "revoked_at": null
                        }
                    }
                }
            ]
        }
    }
}

message: پیغام جزییات صورت‌حساب
data: جزییات صورت‌حساب