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

ساخت و ویرایش درگاه پرداخت

فعال کردن درگاه پرداخت

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

جعبه ابزار

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

جعبه ابزار

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

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

بعد از کلیک روی ساخت درگاه از این قسمت باید تنظیمات درگاه پرداخت را وارد کنید. آدرس وبسایت حتما باید به http یا https وارد شود.

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

تفاوت درگاه اختصاصی و یا اشتراکی چیست؟

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

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

نکته! اگر درگاه اشتراکی فعال دارید با تغییر به درگاه اختصاصی هیچ اختلالی در روند فعلی شما پیش نمی‌آید.

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

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

پیاده سازی فنی درگاه پرداخت

مقدمه

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

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

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

این چهار مرحله کلی مقدمه چهار نکته مهم است که توجه شما را به این نکات جلب می‌کنم.

نکته! تعداد زیادی از کسب و کارها قبل از تایید یک تراکنش و نهایی کردن اون ممکنه به اطلاعات تراکنش نیاز داشته باشند. به عنوان مثال اگر بخواهید شماره کارت پرداخت کننده را قبل از نهایی کردن تراکنش صحت سنجی کنید مرحله سوم که دریافت اطلاعات شماره کارت است رو فراخوانی می‌کنید و پارامتر "cid" که هش "SHA256" شماره کارت است را با شماره کارتی که پرداخت کننده از قبل نزد شما ثبت کرده است، تطابق می‌دهید. اما اگر به این صحت سنجی نیاز نداشته باشید. فراخوانی این سرویس اختیاری است.
نکته! اگر کسب و کار و درگاه پرداخت شما تایید نشده است و در مراحل تایید است. و قصد پیاده سازی درگاه را دارید از همکاران پشتیبان وندار بخواهید شما را به کسب و کاری با نام "سند باکس" عضو کنند و "api_key" تست دریافت کنید. بعد از پیاده سازی و تایید شدن درگاه تنها لازم است که کلید جدید را جایگزین کلید تست کنید.
نکته! این ورژن آخرین ورژن درگاه پرداخت وندار است. ورژن های قدیمی وندار پابرجا است. اما با توجه به تغییرات انجام شده سرعت انجام تراکنش در این ورژن بالاتر است. و این ورژن قابلیت های درگاه پرداخت دومرحله ای و تک مرحله ای را همزمان داراست.
به هیچ عنوان در ورودی و خروجی ها تغییر داده نشده است. پس فقط با تغییر آدرس می‌توانید به ورژن ۳ مهاجرت کنید.
نکته! در صورتیکه تمایل به استفاده از قابلیت سوئیچینگ هوشمند درگاه پرداخت دارید این موضوع را به پشتیبانی وندار اطلاع دهید تا برای شما فعال کنند.

مرحله اول: ارسال اطلاعات و دریافت توکن

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

METHOD: post
URL: https://ipg.vandar.io/api/v3/send

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

Name Type Status
api_key string required
amount Integer required
callback_url String required
mobile_number String optional
factorNumber String optional
description String optional
national_code String optional
valid_card_number String|Array optional
port String optional

توضیحات

  • api_key (اجباری): این کلید بعد از ساخت درگاه پرداخت صادر می‌شود. برای دریافت این کلید به داشبورد وندار مراجعه کنید
  • amount (اجباری): مبلغ تراکنش به صورت ریالی و بزرگتر یا مساوی 1000
  • callback_url (اجباری): باید با آدرس درگاه پرداخت تایید شده در وندار بر روی یک دامنه باشد
  • mobile_number (اختیاری): شماره موبایل (اختیاری، جهت نمایش کارت های خریدار به ایشان و نمایش درگاه موبایلی )
  • factorNumber (اختیاری): شماره فاکتور شما (اختیاری)
  • description (اختیاری): توضیحات (اختیاری، حداکثر 255 کاراکتر)
  • national_code (اختیاری): کد ملی معتبر (در صورت ارسال کد ملی، کاربر فقط با کارت‌های بانکی تحت مالکیت آن کد ملی قابلیت پرداخت خواهد داشت. برای بررسی کدملی در درگاه پرداخت ارسال شماره موبایل مرتبط با کد ملی نیز الزامی است.)
  • valid_card_number (اختیاری): درصورتی که پذیرنده خواستار الزام خریدار به استفاده از یک یا چند کارت خاص باشد، کارت یا کارت های خریدار را به صورت آرایه و حداکثر تا 10 شماره کارت در این کلید قرار می‌دهد.
  • comment (اختیاری): یک یادداشت که در داشبورد شما روی تراکنش نمایش داده می شود.
    • 1
  • port: در صورتی که نیاز به استفاده از پورت خاصی دارید می توانید با استفاده از این پارامتر پورت را انتخاب کنید این گزینه می تواند SAMAN و یا BEHPARDAKHT باشد
نکته! دقت داشته باشید که آدرس بازگشتی شما (callback_url) باید از 255 کاراکتر کمتر باشد در غیر اینصورت خطای سرور دریافت خواهید کرد.

نمونه json 

{
    "api_key": "کلید درگاه پرداخت دریافتی از پنل",
    "amount": 1000,
    "callback_url": "https://example.com/callback",
    "mobile_number": "09123456789",
    "factorNumber": "12345",
    "description": "توضیحات دلخواه",
    
    "valid_card_number": "شماره کارت معتبر",
}
نکته! آدرس بازگشتی در فرایند پرداخت وندار بسیار مهم است. از بخش تنظیمات درگاه پرداخت می‌توانید تعداد نامحدودی آدرس وبسایت به درگاه پرداخت خود اضافه کنید. لطفا دامنه و تمامی ساب دامنه‌های وبسایت خود را که قصد دارید به عنوان آدرس بازگشتی ارسال نمایید را به پنل خود اضافه کنید. هنگام وارد کردن آدرس ها به http و https هم دقت کنید. در صورت رعایت نکردن این نکات خطای آدرس بازگشتی نامعتبر است را دریافت می‌کنید تنظیمات درگاه پرداخت تنظیمات درگاه پرداخت

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

HTTP/1.1 200
{
    "status": 1,
    "token": "توکن پرداختی که در مراحل بعدی مورد استفاده قرار می‌گیرد.",
}
  • status: مقدار 0 و 1 دارد که نشان دهنده موفقیت آمیز بودن درخواست است
  • token: یک رشته از حروف و اعداد است با طول متغییر، که توکن پرداخت است و باید سمت پذیرنده نگهداری شود.

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

HTTP/1.1 4xx
{
    "status": 0,
    "errors": [
        "وارد کردن api key الزامی است",
        "api_key معتبر نیست",
        "IP پذیرنده معتبر نیست",
        "وارد کردن callback_url الزامی است",
        "callback_url معتبر نیست",
        "وارد کردن amount الزامی است",
        "amount نباید کوچکتر از 1000 باشد",
        "amount باید عدد یا رشته‌ای از اعداد باشد",
        "کد ملی قابل قبول نیست.",
        "شماره کارت قابل قبول نیست.",
        
    ]
}
  • status: مقدار 0 و 1 دارد که نشان دهنده موفقیت آمیز بودن درخواست است
  • errors: آرایه ای از خطا‌ها

مرحله دوم: انتقال کاربر به صفحه پرداخت

اگر در مرحله ارسال اطلاعات، اطلاعات ارسالی صحیح باشد و دو مقدار status و token را دریافت کرده باشید. باید کاربر را به شیوه‌ی زیر به درگاه redirect کنید. برای این کار باید عددی که در مرحله اول در متغیر {token} دریافت کردید را در آخر آدرس قرار دهید و کاربر را به URL ایجاد شده redirect کنید تا بلافاصله کاربر به درگاه پرداخت هدایت شده و سپس مرحله سوم را انجام دهید.

METHOD: get
URL: https://ipg.vandar.io/v3/{token}
نکته! این آدرس یک بار مصرف است، به این معنی که اگر بیش از یک بار صدا زده شود خطای 404 دریافت می‌کنید.
نکته! بعد از این مرحله منتظر بمانید که کاربر از صفحه پرداخت برگردد. بعد از بازگشت دو پارامتر token و payment_status به انتهای آدرس بازگشتی اضافه شده است. مانند تصویر زیر.
آدرس بازگشتی اگر payment_status مقداری غیر از OK داشت همینجا می‌توانید فرایند پرداخت را متوقف کنید. اما اگر OK (با حروف بزگ) بود باید تصمیم بگیرید که آیا برای تکمیل تراکنش به مشخصات تراکنش مانند هش شماره کارت نیاز دارید یا خیر. اگر نیاز دارید بعد از این مرحله باید مرحله سوم و بعد چهارم را پیاده سازی کنید. اگه نیاز ندارید، مرحله سوم را نادیده بگیرید و مرحله آخر که تایید تراکنش است را پیاده سازی کنید.

مرحله سوم: دریافت اطلاعات تراکنش

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

METHOD: post
URL: https://ipg.vandar.io/api/v3/transaction

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

Name Type Status
api_key string required
token string required

توضیحات

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

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

HTTP/1.1 200
{
    "status": 1,
    "amount": "10000",
    "transId": 155058785697,
    "refnumber": "GmshtyjwKSuZXT81+6o9nKIkOcW*****PY05opjBoF",
    "trackingCode": "23***6",
    "factorNumber": null,
    "mobile": null,
    "description": "description",
    "cardNumber": "603799******6299",
    "CID": "ECC1F6931DDC1B8A0892293774836F3FFAC4A3C9D34997405F340FCC1BDDED82",
    "createdAt": "2019-02-19 18:19:55",
    "paymentDate": "2019-02-19 18:21:50",
    "code" : 1
    "message": "Confirm requierd"
}
  • status: مقدار 0 و 1 دارد که نشان دهنده موفقیت آمیز بودن درخواست است
  • amount: مبلغ تراکنش که ممکن است با مبلغ تراکنشی که در مرحله اول ارسال کرده باشید متفاوت باشد. اگر کارمزد تراکنش بر عهده پرداخت کننده باشد. مبلغ کارمزد هم به مبلغ تراکنش ارسالی از سمت شما اضافه شده است.
  • transId: شناسه یکتای پرداخت که برای پیگیری تراکنش از وندار مورد استفاده قرار می‌گیرد.
  • refnumber: رسید دیجیتال یکتا در شبکه پرداخت کشور.
  • trackingCode: کد رهگیری به همراه تاریخ انجام تراکنش یکتا است.
  • factorNumber: شماره فاکتوری که شما در مرحله اول ارسال کردید.
  • description: توضیحاتی که شما در مرحله اول ارسال کردید.
  • cardNumber: ماسکه شده شماره کارت پرداخت کننده.
  • CID: هش شماره کارت که با الگوریتم SHA256 هش شده است.
  • createdAt: تاریخ و زمان ایجاد تراکنش.
  • paymentDate: تاریخ و زمان انجام تراکنش.
  • code: کد وضعیت انجام تراکنش.
    • 0 : اطلاعات تراکنش اشتباه است
    • 1 : تراکنش منتظر تاییداست
    • 2 : تراکنش از قبل تایید شده است
    • 3 : تراکنش منقضی شده است(مدت زمان انقضای تراکنش از زمان انتقال به صفحه پرداخت تا تایید 20 دقیقه است)
    • 4 : تراکنش تراکنش ناموفق بوده و نتیجه از قبل اعلام شده است.
  • message: وضعیت تراکنش

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

HTTP/1.1 4xx
{
    "status": 0,
    "errors": [
      "وارد کردن api key الزامی است",
      "api_key معتبر نیست",
      "IP پذیرنده معتبر نیست",
      "وارد کردن token الزامی است",
      "token معتبر نیست",
      "تراکنش با خطا مواجه شده است"
    ]
}
  • status: مقدار 0 و 1 دارد که نشان دهنده موفقیت آمیز بودن درخواست است
  • errors: آرایه ای از خطا‌ها

مرحله چهارم: تایید تراکنش

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

METHOD: post
URL: https://ipg.vandar.io/api/v3/verify

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

Name Type Status
api_key string required
token string required

توضیحات

  • api_key (اجباری): این کلید بعد از ساخت درگاه پرداخت صادر می‌شود. برای دریافت این کلید به داشبورد وندار مراجعه کنید
  • token (اجباری): همان توکن پرداختی که در مرحله یک دریافت کردید و در این مرحله از به صورت انتهای آدرس بازگشتی اضافه شده است.

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

HTTP/1.1 200
{
    "status": 1,
    "amount": "1000.00",
    "realAmount": 500,
    "wage": "500",
    "transId": 159178352177,
    "factorNumber": "12345",
    "mobile": "09123456789",
    "description": "description",
    "cardNumber": "603799******7999",
    "paymentDate": "2020-06-10 14:36:30",
    "cid": null,
    "message": "ok"
}
  • status: مقدار 0 و 1 دارد که نشان دهنده موفقیت آمیز بودن درخواست است
  • amount: مبلغ تراکنش که ممکن است با مبلغ تراکنشی که در مرحله اول ارسال کرده باشید متفاوت باشد. اگر کارمزد تراکنش بر عهده پرداخت کننده باشد. مبلغ کارمزد هم به مبلغ تراکنش ارسالی از سمت شما اضافه شده است.
  • realAmount: مبلغی که بر اساس این تراکنش کیف پول شما بالا رفته است.
  • wage: کارمزد تراکنش
  • transId: شناسه یکتای پرداخت که برای پیگیری تراکنش از وندار مورد استفاده قرار می‌گیرد.
  • factorNumber: شماره فاکتوری که شما در مرحله اول ارسال کردید.
  • mobile: شماره موبایل پرداخت کننده که در حرحله اول ارسال کردید.
  • description: توضیحاتی که شما در مرحله اول ارسال کردید.
  • cardNumber: ماسکه شده شماره کارت پرداخت کننده.
  • paymentDate: تاریخ انجام تراکنش.
  • cid: هش شماره کارت که با الگوریتم SHA256 هش شده است.
  • message: وضعیت تراکنش

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

HTTP/1.1 4xx
{
    "status": 0,
    "errors": [
      "نتیجه تراکنش قبلا از طرف وندار اعلام گردیده.",
      "وارد کردن api key الزامی است",
      "api_key معتبر نیست",
      "IP پذیرنده معتبر نیست",
      "وارد کردن token الزامی است",
      "token معتبر نیست",
      "تراکنش با خطا مواجه شده است"
    ]
}
  • status: مقدار 0 نشان دهنده اشتباه بودن مقادیر ارسالی می باشد
  • status: مقدار 2 نشان دهنده اینکه از قبل وریفای شده است
  • status: مقدار 3 به معنای اینکه زمان تایید تراکنش(حد اکثر ۲۰ دقیقه بعد از ارسال تراکنش) منقضی شده است
  • errors: آرایه ای از خطا‌ها