Gateway Laravel Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require fahipaydev/gateway-laravel
   

2. Publish config:

   php artisan vendor:publish --provider="FahiPay\Gateway\GatewayServiceProvider" --tag="config"
   

3. Configure .env:

   FAHIPAY_MERCHANT_ID=your_merchant_id
   FAHIPAY_SECRET_KEY=your_secret_key
   FAHIPAY_CALLBACK_URL=https://yourdomain.com/fahipay/callback
   

4. Add callback route (in routes/web.php):

   Route::post('/fahipay/callback', [FahiPayCallbackController::class, 'handleCallback']);
   

First Use Case: One-Time Payment

use FahiPay\Gateway\Facades\FahiPay;

$transaction = FahiPay::createTransaction([
    'amount' => 1000, // MVR (e.g., 1000 = MVR 10.00)
    'currency' => 'MVR',
    'description' => 'Order #12345',
    'customer_email' => 'user@example.com',
    'customer_name' => 'John Doe',
    'redirect_url' => route('payment.success'),
    'cancel_url' => route('payment.cancel'),
]);

• Redirect user to $transaction->payment_url.

Implementation Patterns

Core Workflows

1. Payment Flow (Redirect-Based)

// 1. Initiate transaction (returns payment_url)
$txn = FahiPay::createTransaction($data);

// 2. Redirect user to $txn->payment_url
return redirect()->away($txn->payment_url);

// 3. Handle callback (automatically verifies signature)
public function handleCallback(Request $request) {
    $response = FahiPay::handleCallback($request);
    if ($response->isSuccessful()) {
        // Update order status, send confirmation, etc.
    }
}

2. Silent Post (Server-to-Server)

For high-security scenarios (e.g., subscriptions), use silent post by:

• Configuring FAHIPAY_SILENT_POST_URL in .env.
• Validating the signature in the callback payload:

  $isValid = FahiPay::validateCallbackSignature($request->all());
  

3. Transaction Status Checks

// Poll transaction status (e.g., for async workflows)
$status = FahiPay::getTransactionStatus($transactionId);
if ($status->status === 'completed') {
    // Process payment
}

Integration Tips

Database Integration

• Store transaction_id and status in your orders table.
• Use Laravel events (FahiPay\Events\TransactionCreated, FahiPay\Events\TransactionUpdated) to trigger actions:

  // In EventServiceProvider
  protected $listen = [
      'FahiPay\Events\TransactionCreated' => [
          OrderPaid::class,
      ],
  ];
  

Testing

• Use the FahiPay facade with mock responses:

  $this->mock(FahiPay::class)->shouldReceive('createTransaction')
      ->once()
      ->andReturn((object) ['payment_url' => 'https://test.fahipay.mv']);
  

Custom Views

• Override default views by publishing assets:

  php artisan vendor:publish --provider="FahiPay\Gateway\GatewayServiceProvider" --tag="views"
  

• Modify resources/views/vendor/fahipay/redirect.blade.php for branding.

Gotchas and Tips

Pitfalls

1. Signature Mismatch:

   • Issue: Callback validation fails due to incorrect FAHIPAY_SECRET_KEY.
   • Fix: Regenerate the key in FahiPay dashboard and update .env.
   • Debug: Log $request->all() and compare with FahiPay’s expected payload.

2. Amount Formatting:

   • Issue: FahiPay expects amounts in cents (e.g., MVR 10.00 = 1000).
   • Fix: Ensure your amount field is an integer, not a float.

3. Redirect URLs:

   • Issue: redirect_url/cancel_url must be HTTPS and publicly accessible.
   • Fix: Use absolute URLs (e.g., https://yourdomain.com/payment/success).

4. Idempotency:

   • Issue: Retrying failed transactions may create duplicates.
   • Fix: Use idempotency_key in createTransaction():

     $txn = FahiPay::createTransaction([
         'amount' => 1000,
         'idempotency_key' => 'unique_order_123',
     ]);
     

Debugging

• Enable Logging: Add to .env:

  FAHIPAY_LOG_ENABLED=true
  FAHIPAY_LOG_LEVEL=debug
  

• Test Mode: Use FahiPay’s sandbox environment (configure FAHIPAY_ENVIRONMENT=sandbox).

Extension Points

1. Custom Fields: Add metadata to transactions:

   $txn = FahiPay::createTransaction([
       'amount' => 1000,
       'custom_fields' => [
           'order_id' => 123,
           'user_id' => 456,
       ],
   ]);
   

   Retrieve via getTransactionStatus():

   $status = FahiPay::getTransactionStatus($txn->transaction_id);
   $orderId = $status->custom_fields['order_id'];
   

2. Webhook Overrides: Extend FahiPay\Services\CallbackHandler to add custom logic:

   FahiPay::extend(function ($service) {
       $service->onCallback(function ($payload) {
           // Custom logic (e.g., log to third-party system)
       });
   });
   

3. Rate Limiting: Throttle API calls to avoid hitting FahiPay’s limits:

   use Illuminate\Cache\RateLimiting\Limit;
   
   RateLimiter::for('fahipay', function (Request $request) {
       return Limit::perMinute(10)->by($request->user()?->id);
   });