‏پی‌زفیر: یک API برای هشت درگاه پرداخت

PayZephyr یه پکیج پرداخت برای لاراوله که Nwaneri Chukwunyere Kenneth نوشته. به نوشتهٔ لاراول‌نیوز، ایدهٔ اصلیش اینه که هشت درگاه پرداخت رو پشت یک API روان (fluent، یعنی متدها رو پشت سر هم زنجیر می‌کنی) بذاره: Paystack، Stripe، PayPal، Flutterwave، Square، Monnify، OPay و Mollie. یعنی کدی که تو اپت می‌نویسی برای همهٔ اینا یکیه و عوض کردن درگاه کار کانفیگه، نه بازنویسی کد.

گرفتن پرداخت با facadeای به اسم Payment انجام می‌شه: مبلغ و ایمیل و یه reference می‌دی و با متد amount()، email() و callback() کاربر رو به صفحهٔ چک‌اوت درگاه می‌فرستی. وقتی برگشت، با همون reference و متد verify() نتیجه رو چک می‌کنی و اگه isSuccessful() بود سفارش رو پرداخت‌شده علامت می‌زنی:

Route::get('/payment/callback', function (Request $request) {
    $verification = Payment::verify($request->query('reference'));

    if ($verification->isSuccessful()) {
        // Mark the order paid.
    }
});

نکتهٔ جالبش failover هست: دو تا متغیر محیطی می‌دی، یکی درگاه پیش‌فرض و یکی جایگزین، و وقتی اولی خطا بده پکیج خودش می‌ره سراغ دومی. برای فروشگاهی که قطعی درگاه براش یعنی سفارش از دست رفته، همین دو خط ارزش داره:

PAYMENTS_DEFAULT_PROVIDER=paystack
PAYMENTS_FALLBACK_PROVIDER=stripe

کنارش محافظت در برابر پرداخت دوباره هم هست تا مشتری دو بار پول نده، و وب‌هوک‌ها امضاشده‌ان و جلوی replay (یعنی فرستادن دوبارهٔ همون پیام) رو می‌گیرن. برای اشتراک با متد planData و یه SubscriptionPlanDTO پلن می‌سازی (اسم، مبلغ، دورهٔ ماهانه، ارز) و بعد کاربر رو با subscribe() روی همون پلن می‌بری، و idempotency() جلوی ثبت تکراری رو می‌گیره.

بازگشت وجه کامله، ولی اگه amount() بدی فقط همون مقدار برمی‌گرده و می‌تونی دلیلش رو هم ثبت کنی. مقاله یادآوری می‌کنه که بعضی درگاه‌ها بازگشت وجه رو دیرتر تسویه می‌کنن، پس باید $refund->isPending() رو ببینی و منتظر وب‌هوک بمونی، نه اینکه به جواب همون لحظه تکیه کنی.

نصبش با Composer و بعد اجرای دستور payzephyr:installه. سورس روی گیت‌هابه و مستنداتش درایور سفارشی، اتصال به queue و یه چک‌لیست production رو پوشش می‌ده. یه playground هم داره که بدون نصب، API رو تست کنی.

نکات کلیدی:

• هشت درایور (Paystack، Stripe، PayPal، Flutterwave، Square، Monnify، OPay، Mollie) پشت یک facade به اسم Payment
• failover خودکار با دو متغیر PAYMENTS_DEFAULT_PROVIDER و PAYMENTS_FALLBACK_PROVIDER
• جلوگیری از پرداخت دوباره، و وب‌هوک امضاشده با محافظت در برابر replay
• اشتراک با SubscriptionPlanDTO و planData؛ بازگشت وجه بخشی با amount()
• بعضی درگاه‌ها بازگشت وجه رو دیرتر تسویه می‌کنن، پس isPending() رو چک کن
• نصب با composer require kendenigerian/payzephyr و بعد php artisan payzephyr:install