Payexa Wallet Demo - Ruby (Sinatra)

اين پروژه يک نمونه آموزشي براي اتصال درگاه Payexa به اپليکيشن Ruby (با Sinatra) است.

هدف اين مثال اين است که منطق پرداخت را به صورت کامل و قابل فهم نشان دهد، نه اينکه جايگزين يک محصول نهايي production باشد.

اين مثال چه کاربردي دارد؟

اين مثال براي موارد زير مناسب است:

• آموزش تيم توسعه براي درک جريان پرداخت Payexa
• ساخت PoC (نمونه اوليه سريع) قبل از پياده سازي در Rails يا سرويس اصلي
• تست عملي callback و verify در محيط sandbox
• الگوبرداري از منطق امن افزايش موجودي کيف پول

اگر بخواهي در سايت واقعي پرداخت ريالي پياده کني، اين مثال يک نقطه شروع خوب براي معماري و منطق تراکنش است.

جريان پرداخت در اين مثال

1. کاربر مبلغ شارژ را ثبت مي کند.
2. برنامه سفارش شارژ را ايجاد مي کند (pending).
3. برنامه به request در Payexa درخواست مي دهد.
4. کاربر به صفحه پرداخت (startPay) هدايت مي شود.
5. درگاه callback را به اپليکيشن برمي گرداند.
6. برنامه پرداخت را با endpoint verify دوباره بررسي مي کند.
7. فقط در صورت verify موفق، موجودي کيف پول افزايش پيدا مي کند.

چرا اين مثال مهم است؟

• callback به تنهايي براي شارژ کيف پول کافي نيست.
• وضعيت نهايي بايد با verify سرور-به-سرور تاييد شود.
• براي جلوگيري از شارژ دوباره، از فيلد credited استفاده شده است (idempotency).

راه اندازي

cd examples/ruby-sinatra
cp .env.example .env
bundle install
bundle exec ruby app.rb

آدرس پيش فرض:

http://127.0.0.1:5052/

تنظيمات محيطي مهم

فايل نمونه تنظيمات: .env.example

مهم ترين متغيرها:

• PAYEXA_BASE_URL: آدرس sandbox يا production
• PAYEXA_API_KEY: کليد API مرچنت
• PAYEXA_STARTPAY_PATH: مسير شروع پرداخت (مثل /startPay)
• PAYEXA_REQUEST_ENDPOINT: اندپوینت request
• PAYEXA_VERIFY_ENDPOINT: اندپوینت verify
• PAYEXA_CALLBACK_PATH: مسير callback اپ
• PAYEXA_PUBLIC_CALLBACK_URL: callback کامل براي ارسال به درگاه (اختياري)

نکته مهم براي لوکال:

• Sinatra در اين مثال با WEBrick اجرا مي شود (تک ترد).
• بعضي درگاه ها هنگام request، callback را همان لحظه چک مي کنند.
• اگر callback روي همين سرور باشد، ممکن است request قفل شود و ريدایرکت انجام نشود.
• در اين حالت PAYEXA_PUBLIC_CALLBACK_URL را ست کن (مثلا http://127.0.0.1:5052/payments/callback يا يک URL عمومي).

نحوه تست سريع

1. صفحه اصلي را باز کن: http://127.0.0.1:5052/
2. يک مبلغ وارد کن و روي دکمه شارژ بزن.
3. اگر request موفق باشد، به صفحه پرداخت هدايت مي شوي.
4. پس از callback، نتيجه verify را در صفحه نتيجه پرداخت مي بيني.
5. در صفحه اصلي، ليست سفارش ها و وضعيت credited قابل مشاهده است.

محدوديت هاي اين نسخه

• داده ها در حافظه نگهداري مي شوند (با ري استارت برنامه پاک مي شوند).
• براي دمو ساخته شده و هنوز logging/monitoring حرفه اي ندارد.
• براي production بايد DB واقعي، مدل تراکنش اتميک، و مديريت خطاي کامل اضافه شود.

مناسب براي چه کسي؟

• توسعه دهنده Ruby که مي خواهد Payexa را سريع تست کند.
• تيم محصول که مي خواهد flow پرداخت را قبل از توسعه نهايي ببيند.
• پروژه اي که مي خواهد از اين کد به عنوان reference implementation استفاده کند.

نکات امنيتي

• API Key را هرگز در فرانت اند قرار نده.
• .env را commit نکن.
• افزايش موجودي را فقط بعد از verify موفق انجام بده.
• callback هاي تکراري را با idempotency کنترل کن.