سرویس پرداخت آنلاین

مستندات سرویس پرداخت آنلاین هما

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

1. معماری کلی سرویس پرداخت

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

1. در سیستم خودتان (سایت یا اپلیکیشن)، برای کاربر یک فاکتور یا آبجکت قابل پرداخت ایجاد می‌کنید.
2. کاربر روی دکمه «پرداخت آنلاین» کلیک می‌کند.
3. سیستم شما یک لینک پرداخت هما می‌سازد و کاربر را با Redirect به آن آدرس منتقل می‌کند.
4. هما فرآیند پرداخت را انجام می‌دهد (درگاه بانکی، اعتبار، و ...).
5. پس از موفق یا ناموفق بودن پرداخت، کاربر به آدرس‌های بازگشت ROS یا ROF در سایت شما هدایت می‌شود.
6. در صفحه بازگشت، شما وضعیت پرداخت را بررسی کرده و وضعیت فاکتور را در سیستم خودتان به‌روزرسانی می‌کنید.

2. آدرس سرویس پرداخت

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

https://api.homais.com/services/payment/
  

همه اطلاعات پرداخت از طریق Query String به این آدرس ارسال می‌شود و کاربر با HTTP Redirect به آن هدایت می‌شود.

3. پارامترهای مورد نیاز در Query String

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

نام پارامتر	نوع	اجباری	توضیح
portalcode	Int	بله	کد پرتال شما در هما (توسط تیم هما به شما تخصیص داده می‌شود).
CellNumber	String	بله	شماره موبایل کاربر پرداخت‌کننده.
memberid	Long	بله	شناسه کاربر/عضو در هما (MemberID یا CustomerID).
amount	Long	بله	مبلغ پرداخت (معمولاً به ریال). اگر کمتر از 10٬000 ارسال شود، به 10٬000 گرد می‌شود.
clubID	Long	پیشنهادی	برابر با portalcode است.
byCredit	Bool	اختیاری	اگر مقدار True باشد پرداخت از اعتبار کیف پول در هما انجام می‌شود، در غیر این صورت پرداخت درگاه بانکی است.
objectType	Int	پیشنهادی	عدد ثابت 100 وارد شود.
objectID	Long	پیشنهادی	شناسه فاکتور یا رکورد قابل پرداخت در سیستم شما.
PaymentType	Int	اختیاری	نوع پرداخت (مثلاً 1 = پرداخت آنلاین). معنای مقادیر طبق قرارداد بین شما و هما تعیین می‌شود.
ROS	URL	بله	آدرس بازگشت در صورت پرداخت موفق (Return On Success). این آدرس باید از بیرون قابل دسترسی باشد.
ROF	URL	بله	آدرس بازگشت در صورت پرداخت ناموفق (Return On Fail).

پارامترهای ROS و ROF باید به‌صورت URL-Encode شده ارسال شوند. همچنین پیشنهاد می‌شود مقادیر ثابت مانند objectType و PaymentType را در سیستم خودتان به‌عنوان ثابت (Constant) تعریف کنید تا در تمام پروژه، یکسان استفاده شوند.

4. الگوریتم استفاده از سرویس پرداخت هما

1. کاربر در سیستم شما لاگین کرده و فاکتور مورد نظر برای او ثبت می‌شود.
2. در صفحه نمایش فاکتور، دکمه «پرداخت آنلاین با هما» نمایش داده می‌شود.
3. با کلیک کاربر روی دکمه، سیستم شما یک URL کامل برای سرویس پرداخت هما می‌سازد.
4. کاربر با HTTP Redirect به آن URL هدایت می‌شود.
5. هما عملیات پرداخت را انجام می‌دهد.
6. پس از پایان پرداخت، کاربر به یکی از آدرس‌های ROS (موفق) یا ROF (ناموفق) در سایت شما بازگردانده می‌شود.
7. در صفحه بازگشت، شما وضعیت پرداخت را بررسی کرده، فاکتور را به‌روزرسانی و پیام مناسب را به کاربر نمایش می‌دهید.

5. مثال پیاده‌سازی با پایتون (Flask)

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

5.1. تابع ساخت لینک پرداخت هما

from urllib.parse import urlencode
from flask import Flask, redirect, url_for

app = Flask(__name__)

HOMA_BASE_URL = "https://api.homais.com/services/payment/"
PORTAL_CODE = 8486
CLUB_ID = 8486
OBJECT_TYPE_INVOICE = 100
PAYMENT_TYPE_ONLINE = 1


def build_homa_payment_url(user_mobile, member_id, amount, invoice_id, return_url_success, return_url_fail):
    if amount < 10000:
        amount = 10000

    params = {
        "portalcode": PORTAL_CODE,
        "CellNumber": user_mobile,
        "memberid": member_id,
        "amount": amount,
        "clubID": CLUB_ID,
        "byCredit": "False",
        "objectType": OBJECT_TYPE_INVOICE,
        "objectID": invoice_id,
        "PaymentType": PAYMENT_TYPE_ONLINE,
        "ROS": return_url_success,
        "ROF": return_url_fail,
    }

    return HOMA_BASE_URL + "?" + urlencode(params)
  

5.2. مسیر شروع پرداخت (Redirect به هما)

@app.route("/pay/<int:invoice_id>")
def pay_invoice(invoice_id):
    user_mobile = "09120000000"
    member_id = 12345
    amount = 250000

    ros = url_for("payment_success", invoice_id=invoice_id, _external=True)
    rof = url_for("payment_fail", invoice_id=invoice_id, _external=True)

    homa_url = build_homa_payment_url(
        user_mobile=user_mobile,
        member_id=member_id,
        amount=amount,
        invoice_id=invoice_id,
        return_url_success=ros,
        return_url_fail=rof,
    )

    return redirect(homa_url)
  

در پیاده‌سازی واقعی، مقادیر user_mobile، member_id، amount و سایر اطلاعات باید از دیتابیس یا سیستم احراز هویت شما خوانده شوند.

5.3. صفحات بازگشت پرداخت موفق/ناموفق

@app.route("/payment/success/<int:invoice_id>")
def payment_success(invoice_id):
    return f"پرداخت فاکتور {invoice_id} با موفقیت انجام شد."


@app.route("/payment/fail/<int:invoice_id>")
def payment_fail(invoice_id):
    return f"پرداخت فاکتور {invoice_id} ناموفق بود."
  

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

6. چک‌لیست برای توسعه‌دهندگان

• دریافت portalcode (و در صورت نیاز clubID) از تیم هما.
• تعیین مقادیر ثابت برای objectType (مثلاً فاکتور فروش) و PaymentType (مثلاً پرداخت آنلاین).
• تعریف دو آدرس عمومی در سایت خودتان برای ROS و ROF (بازگشت موفق و ناموفق).
• پیاده‌سازی تابعی برای ساخت URL پرداخت هما با پارامترهای ذکر شده.
• انجام Redirect کاربر به لینک هما در زمان کلیک روی دکمه «پرداخت آنلاین».
• مدیریت وضعیت فاکتور در صفحات بازگشت و نمایش پیام مناسب به کاربر.

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