مستندات فنی API

راهنمای کامل توسعه‌دهندگان برای یکپارچه‌سازی با هیلاپی

شروع به کار

به مستندات API هیلاپی خوش آمدید. این راهنما به شما کمک می‌کند تا به سرعت با سرویس‌های ما یکپارچه شوید.

پیش‌نیازها

  • حساب کاربری فعال در هیلاپی
  • JWE Token از پنل کاربری
  • دانش پایه HTTP و RESTful API
  • یک زبان برنامه‌نویسی (PHP, Python, JavaScript, و غیره)

Base URL

تمام درخواست‌های API به آدرس زیر ارسال می‌شوند:

https://api.hillapay.ir/
نکته: برای محیط تست از آدرس https://sandbox.hillapay.ir/v1/ استفاده کنید.

نصب SDK

برای سهولت در کار، SDK های آماده برای زبان‌های مختلف فراهم کرده‌ایم:

PHP

composer require hillapay/php-sdk

Python

pip install hillapay-python

Node.js

npm install hillapay-node

احراز هویت

تمام درخواست‌های API نیاز به احراز هویت دارند. هیلاپی از JWE Token برای احراز هویت استفاده می‌کند.

دریافت JWE Token

  1. وارد پنل کاربری خود شوید
  2. به بخش "مدیریت Token" بروید
  3. روی "ایجاد کلید جدید" کلیک کنید
  4. JWE Token را در جای امن ذخیره کنید
⚠️ هشدار: JWE Token را هرگز در کد سمت کلاینت (Frontend) قرار ندهید. این کلید باید فقط در سرور شما استفاده شود.

نحوه استفاده

برای احراز هویت، باید در هدر درخواست‌های خود JWE Token را قرار دهید:

Authorization: Bearer YOUR_JWE_TOKEN

مثال با cURL

curl -X GET https://api.hillapay.ir/v1/account/info \ -H "Authorization: Bearer YOUR_JWE_TOKEN" \ -H "Content-Type: application/json"

درگاه پرداخت

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

ایجاد پرداخت

برای ایجاد یک درخواست پرداخت جدید، از endpoint زیر استفاده کنید:

POST /payment/create

پارامترهای ورودی

پارامتر نوع الزامی توضیحات
amount Integer ✓ مبلغ به ریال
callback_url String ✓ آدرس بازگشت پس از پرداخت
order_id String ✓ شناسه سفارش در سیستم شما
description String - توضیحات پرداخت
payer_mobile String - شماره موبایل پرداخت‌کننده

مثال درخواست

{ "amount": 100000, "callback_url": "https://yoursite.com/payment/callback", "order_id": "ORD-12345", "description": "خرید محصول", "payer_mobile": "09123456789" }

پاسخ موفق

{ "status": "success", "data": { "payment_id": "PAY-ABC123XYZ", "payment_url": "https://pay.hillapay.ir/gateway/PAY-ABC123XYZ", "expires_at": "2024-03-20T15:30:00Z" } }
✓ نکته: کاربر را به آدرس payment_url هدایت کنید تا پرداخت را انجام دهد.

تایید پرداخت

پس از بازگشت کاربر از درگاه، باید پرداخت را تایید کنید:

POST /payment/verify

پارامترهای ورودی

پارامتر نوع الزامی توضیحات
payment_id String ✓ شناسه پرداخت

مثال پاسخ موفق

{ "status": "success", "data": { "payment_id": "PAY-ABC123XYZ", "order_id": "ORD-12345", "amount": 100000, "card_number": "6037-99**-****-1234", "ref_number": "123456789012", "transaction_id": "TXN-987654321", "verified_at": "2024-03-20T14:25:30Z" } }

استعلام‌های مالی

استعلام کارت بانکی

GET /inquiry/card

مثال درخواست

{ "card_number": "6037997012345678" }

پاسخ

{ "status": "success", "data": { "bank_name": "بانک ملی ایران", "card_type": "DEBIT", "is_valid": true } }

استعلام شماره شبا

GET /inquiry/iban

انتقال وجه

امکان انتقال وجه به حساب‌های بانکی از طریق شبکه پایا و ساتنا

انتقال پایا

POST /transfer/paya
ℹ️ اطلاعات: انتقال پایا معمولاً طی ۲۴ ساعت انجام می‌شود.

Webhooks

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

تنظیم Webhook

  1. در پنل کاربری به بخش Webhooks بروید
  2. URL endpoint خود را وارد کنید
  3. رویدادهای مورد نظر را انتخاب کنید
  4. Secret را ذخیره کنید (برای امضای درخواست‌ها)

رویدادهای پشتیبانی شده

  • payment.success - پرداخت موفق
  • payment.failed - پرداخت ناموفق
  • transfer.completed - انتقال وجه کامل شد
  • transfer.failed - انتقال وجه ناموفق

کدهای خطا

لیست کدهای خطای رایج API:

کد توضیحات راه‌حل
400 درخواست نامعتبر پارامترهای ورودی را بررسی کنید
401 احراز هویت ناموفق API Key را بررسی کنید
403 دسترسی غیرمجاز سطح دسترسی حساب را بررسی کنید
404 منبع یافت نشد آدرس endpoint را بررسی کنید
429 تعداد درخواست بیش از حد چند دقیقه صبر کنید
500 خطای سرور با پشتیبانی تماس بگیرید

SDK ها و کتابخانه‌ها

SDK های رسمی هیلاپی برای زبان‌های مختلف:

🐘

PHP SDK

برای Laravel، Symfony و...

مشاهده در GitHub
🐍

Python SDK

برای Django، Flask و...

مشاهده در GitHub
📦

Node.js SDK

برای Express، NestJS و...

مشاهده در GitHub