Savano Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kpasokhi/savano
   

   Publish the config file (if available) via:

   php artisan vendor:publish --provider="Kpasokhi\Savano\SavanoServiceProvider"
   

2. First Use Case: Initiating a Payment

   • Define a PaymentController with two actions: request (for initiating payment) and verify (for handling callback).
   • Store price, orderId, and authority in your database (e.g., payments table) before redirecting to Savano.

   Example:

   use Kpasokhi\Savano\Facades\Savano;
   
   public function request()
   {
       $pin = config('savano.pin');
       $callback = route('savano.verify');
   
       $savano = Savano::setPin($pin);
       $result = $savano->request(1000, 1, $callback)->getResult();
   
       if ($result === 1) {
           $authority = $savano->getAuthority();
           // Save to DB: price, orderId, authority
           return redirect($savano->getRedirectUrl());
       }
       return back()->with('error', $savano->getErrorMessage());
   }
   

3. Verify Callback

   • Create a route for the Savano callback (e.g., savano/verify).
   • Fetch stored price, orderId, and authority to validate the response.

   Example:

   public function verify(Request $request)
   {
       $payment = Payment::where('order_id', $request->orderId)->firstOrFail();
       $savano = Savano::setPin(config('savano.pin'));
   
       $result = $savano->verify(
           $payment->price,
           $payment->orderId,
           $payment->authority,
           $request->all()
       )->getResult();
   
       if ($result === 1) {
           // Update payment status (e.g., mark as paid)
           return response()->json(['status' => 'success']);
       }
       return response()->json(['status' => 'failed'], 400);
   }
   

Implementation Patterns

Workflows

1. Payment Initiation Flow

   • Pre-Redirect: Save price, orderId, and authority to your database.
   • Redirect: Use $savano->getRedirectUrl() to send users to Savano’s payment page.
   • Post-Redirect: Handle the callback via the verify endpoint.

2. Callback Handling

   • Validation: Always cross-check orderId and authority with stored values.
   • Idempotency: Ensure the verify endpoint is idempotent (e.g., check if payment is already processed).
   • Response: Return a JSON response (e.g., {"status": "success"}) for Savano to acknowledge.

3. Error Handling

   • Use $savano->getErrorMessage() to display user-friendly errors (e.g., invalid pin, network issues).
   • Log errors for debugging:

     \Log::error('Savano Error: ' . $savano->getErrorMessage());
     

Integration Tips

• Database Schema: Add columns like price, order_id, authority, status, and callback_data to your payments table.
• Config File: Customize config/savano.php for default values (e.g., pin, test_mode).
• Testing:
  • Use Savano’s test mode (if supported) to mock transactions.
  • Test callback responses with tools like ngrok for local development.

Gotchas and Tips

Pitfalls

1. Missing Authority Storage

   • Issue: Forgetting to save the authority (returned from request()) before redirecting.
   • Fix: Always store authority in your database and fetch it during verification.

     $authority = $savano->request($price, $orderId, $callback)->getAuthority();
     

2. Callback URL Mismatch

   • Issue: Savano’s callback fails if the callback URL in request() doesn’t match the route.
   • Fix: Use absolute URLs (e.g., route('savano.verify', [], false)) or environment variables.

3. Synchronous Verification Assumption

   • Issue: Assuming the verify endpoint is called immediately after payment.
   • Fix: Design for asynchronous callbacks (e.g., retry logic, webhook validation).

4. No Transaction Rollback

   • Issue: Partial updates (e.g., marking an order as paid before verifying).
   • Fix: Use database transactions or queue jobs for atomic operations.

Debugging

• Enable Logging: Add debug logs for request and verify calls:

  \Log::debug('Savano Request Data:', [
      'price' => $price,
      'orderId' => $orderId,
      'authority' => $authority,
  ]);
  

• Test Mode: If Savano supports it, enable test_mode in config to avoid real transactions during development.

Extension Points

1. Custom Responses

   • Override default responses by extending the Savano class or using middleware:

     Savano::setCallbackHandler(function ($data) {
         // Custom logic (e.g., notify user via email)
     });
     

2. Webhook Validation

   • Add middleware to validate Savano’s callback signatures (if supported):

     Route::middleware('validate.savano.signature')->post('/savano/verify', ...);
     

3. Retry Logic

   • Implement exponential backoff for failed verifications:

     if ($result !== 1) {
         retry()->times(3)->later(5000, fn() => $this->verify(...));
     }