Baofoo Pay Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dwddevops/baofoo-pay-bundle
   

   Publish the configuration file:

   php artisan vendor:publish --provider="Dwddevops\BaofooPayBundle\BaofooPayServiceProvider" --tag="baofoo-pay-config"
   

2. Configuration Edit config/baofoo-pay.php with your Baofoo merchant credentials:

   'merchant_id' => env('BAOFOO_MERCHANT_ID'),
   'merchant_key' => env('BAOFOO_MERCHANT_KEY'),
   'base_url' => env('BAOFOO_BASE_URL', 'https://api.baofoo.com'),
   

3. First Use Case: Create a Payment Inject the service into a controller:

   use Dwddevops\BaofooPayBundle\Services\BaofooPayService;
   
   public function createPayment(BaofooPayService $baofooPay)
   {
       $result = $baofooPay->createPayment([
           'order_id' => 'ORD-12345',
           'amount' => 100.00,
           'currency' => 'USD',
           'subject' => 'Product Purchase',
           'body' => 'Payment for product #123',
       ]);
   
       return response()->json($result);
   }
   

Implementation Patterns

Common Workflows

1. Payment Creation & Processing

   // Create a payment request
   $payment = $baofooPay->createPayment($paymentData);
   
   // Verify payment status (e.g., after redirect)
   $status = $baofooPay->verifyPayment($payment['payment_id']);
   

2. Webhook Handling Configure routes in routes/web.php:

   Route::post('/baofoo-webhook', [BaofooPayController::class, 'handleWebhook']);
   

   Implement the controller:

   public function handleWebhook(Request $request, BaofooPayService $baofooPay)
   {
       $baofooPay->handleWebhook($request->all());
   }
   

3. Refunds

   $refund = $baofooPay->createRefund([
       'order_id' => 'ORD-12345',
       'amount' => 50.00,
       'reason' => 'Customer refund request',
   ]);
   

Integration Tips

• Laravel Events: Extend the bundle by listening to baofoo.payment.created or baofoo.payment.completed events.
• Middleware: Use middleware to validate Baofoo signatures for webhooks:

  $baofooPay->validateWebhookSignature($request->all());
  

• Logging: Enable debug logging in config/baofoo-pay.php for troubleshooting:

  'debug' => env('BAOFOO_DEBUG', false),
  

Gotchas and Tips

Pitfalls

1. Signature Validation

   • Always validate webhook signatures. Baofoo provides a signature field in the payload:

     $isValid = $baofooPay->validateWebhookSignature($request->all());
     

   • Gotcha: If merchant_key is misconfigured, signatures will fail silently. Double-check the key in .env.

2. Async Processing

   • Webhook retries: Baofoo may retry failed webhooks. Implement idempotency checks (e.g., store payment_id in a database before processing).

3. Currency & Amount

   • Ensure amounts are sent as integers (e.g., 100.00 → 10000 for cents). The bundle may not auto-convert; check the API docs.

4. Testing

   • Use Baofoo’s sandbox environment (BAOFOO_BASE_URL=https://sandbox.baofoo.com). Mock the service in tests:

     $this->partialMock(BaofooPayService::class, ['createPayment']);
     

Debugging

• Enable Debug Mode:

  'debug' => true,
  

  Logs will appear in storage/logs/laravel.log.

• Common Errors:

  • InvalidSignatureException: Verify merchant_key and payload order.
  • PaymentNotFound: Ensure order_id or payment_id matches Baofoo’s records.
  • Fix: Use the Baofoo API Explorer to test endpoints manually.

Extension Points

1. Custom Responses Override the default response format by binding a custom formatter:

   $baofooPay->setResponseFormatter(function ($data) {
       return ['success' => true, 'data' => $data];
   });
   

2. Database Storage Extend the bundle to auto-save payments to your database:

   // In a service provider
   $baofooPay->setPaymentSaver(function ($payment) {
       Payment::create($payment);
   });
   

3. Localization Add language support by extending the BaofooPayService class and overriding error messages:

   $baofooPay->setLanguage('zh_CN'); // If supported