Skip to content

README.fa.md

Latest commit

 

History

History
88 lines (62 loc) · 6.2 KB

README.fa.md

File metadata and controls

88 lines (62 loc) · 6.2 KB
Raw

English | فارسی

JS-Basic-Example-Payment

نمونه‌ی ساده و آموزشی اتصال به درگاه پرداخت پی‌پینگ با Node.js — بدون هیچ وابستگی خارجی (فقط Node استاندارد).

این پروژه بر پایه‌ی API نسخه ۳ پی‌پینگ (مسیر v3/pay) پیاده‌سازی شده است.

جریان پرداخت (نسخه ۳)

  1. کاربر فرم صفحه‌ی اصلی را پر می‌کند (ایمیل، موبایل، نام، مبلغ و توضیحات).
  2. POST /payment → سرور با فراخوانی POST api.payping.ir/v3/pay یک دستور پرداخت می‌سازد. پاسخ شامل paymentCode و url آماده‌ی هدایت کاربر است، پس کاربر مستقیماً به همان url ریدایرکت می‌شود.
  3. پس از پرداخت در درگاه بانکی، پی‌پینگ نتیجه را با یک فرم POST به returnUrl (مسیر /verify) می‌فرستد:
    • status: عدد ۱ به‌معنی موفق، ۰ به‌معنی عدم پرداخت
    • errorCode: کد خطای بازگشتی — در موفقیت خالی است
    • data: رشته JSON شامل clientRefId، paymentCode، paymentRefId (کد رهگیری)، amount، gatewayAmount، cardNumber و cardHashPan
  4. اگر status برابر ۱ باشد، سرور با POST api.payping.ir/v3/pay/verify تراکنش را تایید نهایی می‌کند و نتیجه را نمایش می‌دهد.

مهم: اگر verify تا ۱۰ دقیقه پس از پرداخت فراخوانی نشود، پرداخت نامعتبر می‌شود و وجه به حساب پرداخت‌کننده برمی‌گردد.

ساختار پروژه

├── server.js      # کل برنامه: فرم، ساخت پرداخت و تایید تراکنش
├── package.json
├── README.md      # مستندات انگلیسی
└── README.fa.md   # مستندات فارسی
مسیر متد معادل API پی‌پینگ (v3) توضیح
/payment POST POST /v3/pay ساخت پرداخت و ریدایرکت به url برگشتی
/verify POST POST /v3/pay/verify دریافت نتیجه از درگاه و تایید نهایی

پیش‌نیازها

  • Node.js نسخه‌ی ۱۸ یا بالاتر (به‌خاطر fetch داخلی)
  • توکن API از پنل پی‌پینگ (بخش توسعه‌دهندگان ← توکن‌ها)

اجرا

# لینوکس / مک
PAYPING_TOKEN=توکن-شما node server.js

# ویندوز (PowerShell)
$env:PAYPING_TOKEN="توکن-شما"; node server.js

# یا با npm
npm start

سپس مرورگر را روی http://localhost:3000 باز کنید.

تنظیمات (متغیرهای محیطی)

متغیر پیش‌فرض توضیح
PAYPING_TOKEN — توکن دریافتی از payping.ir (اجباری)
PORT 3000 پورت اجرای سرور
RETURN_URL http://localhost:3000/verify آدرس برگشت کاربر پس از پرداخت؛ در حالت واقعی آدرس دامنه‌ی خود را بدهید

مثال حالت واقعی:

PAYPING_TOKEN=xxxx RETURN_URL=https://domain.com/verify PORT=80 node server.js

نکات مهم API نسخه ۳

  • پاسخ ساخت پرداخت علاوه بر paymentCode و url، شامل مبالغ هم هست: amount (مبلغ دستور پرداخت)، gatewayAmount (مبلغ نهایی پرداخت که با توجه به سناریوی کارمزد ممکن است بیشتر باشد) و کارمزدهای payerWage/businessWage و paypingVat.
  • پاسخ verify اطلاعات کامل تراکنش را برمی‌گرداند: مبلغ، شماره کارت ماسک‌شده، clientRefId، تاریخ پرداخت و کارمزدها.
  • وضعیت‌های خاص verify:
    • 409 با metaData.code = 110 → تراکنش قبلاً وریفای شده؛ نیازی به تایید مجدد نیست.
    • 202 یا 502 → تایید هنوز در حال پردازش است؛ verify را مجدداً فراخوانی کنید.
  • فیلدهای اختیاری ساخت پرداخت که در صورت نیاز می‌توانید اضافه کنید: nationalCode، isReversible (امکان بازگشت وجه تا ۳۰ دقیقه پس از وریفای) و isBlocked (پرداخت مسدودشونده برای تسهیم پس از پرداخت با سرویس‌های share/unblock).

نکات مهم برای استفاده‌ی واقعی

  • توکن را هرگز در کد کامیت نکنید؛ فقط از متغیر محیطی استفاده کنید.
  • مبلغ را همیشه سمت سرور تعیین و اعتبارسنجی کنید؛ اعتماد به مبلغ ارسالی از سمت کاربر خطرناک است. در این نمونه برای سادگی، مبلغ از فرم خوانده و به returnUrl الصاق می‌شود و در بازگشت با amount ارسالی پی‌پینگ مقایسه می‌شود — در پروژه‌ی واقعی آن را از فاکتور/دیتابیس بخوانید.
  • طبق مستندات رسمی: پس از بازگشت موفق، صحت amount و clientRefId ارسالی از پی‌پینگ را با پایگاه داده خود مقایسه کنید و در صورت مغایرت از ادامه‌ی فرایند صرف‌نظر کنید (این مقایسه در نمونه انجام می‌شود).
  • بهتر است clientRefId را شماره‌ی فاکتور قرار دهید و نتیجه‌ی verify را به‌همراه paymentRefId در دیتابیس ذخیره کنید تا تراکنش قابل پیگیری باشد.
  • این نمونه صرفاً آموزشی است؛ برای محیط عملیاتی از HTTPS استفاده کنید و تدابیر امنیتی لازم (محدودسازی نرخ درخواست، لاگ‌گیری و…) را بیندیشید.

لایسنس

GPL-3.0 — مطابق مخزن اصلی.