Cybersource Hosted Checkout Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require asciisd/cybersource-hosted-checkout-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Asciisd\CybersourceHostedCheckout\CybersourceHostedCheckoutServiceProvider" --tag="config"
   

2. Configuration Update .env with your CyberSource credentials:

   CYBERSOURCE_MERCHANT_ID=your_merchant_id
   CYBERSOURCE_KEY=your_key
   CYBERSOURCE_SECRET=your_secret
   CYBERSOURCE_ENV=test  # or 'live'
   

3. First Use Case: Redirect to Hosted Checkout

   use Asciisd\CybersourceHostedCheckout\Facades\CybersourceHostedCheckout;
   
   $checkoutUrl = CybersourceHostedCheckout::createCheckout([
       'amount' => 100.00,
       'currency' => 'USD',
       'orderId' => 'order_123',
       'returnUrl' => route('checkout.return'),
       'cancelUrl' => route('checkout.cancel'),
       'customer' => [
           'id' => 'customer_456',
           'name' => 'John Doe',
           'email' => 'john@example.com',
       ],
   ]);
   
   return redirect()->to($checkoutUrl);
   

4. Handling Return Add routes for returnUrl and cancelUrl:

   Route::get('/checkout/return', [CheckoutController::class, 'handleReturn']);
   Route::get('/checkout/cancel', [CheckoutController::class, 'handleCancel']);
   

Implementation Patterns

Workflow: Order Processing

1. Pre-Checkout

   • Generate a unique orderId for tracking.
   • Validate cart contents (e.g., stock, pricing) before redirecting.

2. Post-Return

   public function handleReturn(Request $request)
   {
       $response = CybersourceHostedCheckout::verifyCheckout($request->all());
   
       if ($response->isSuccessful()) {
           // Mark order as paid, update inventory, etc.
           Order::find($response->orderId)->paid();
       } else {
           // Handle failure (e.g., refund, notify customer)
       }
   }
   

3. Webhook Handling (Advanced) Use CyberSource’s transaction notifications to sync payments in real-time:

   Route::post('/cybersource/webhook', [WebhookController::class, 'handle']);
   

   public function handle(Request $request)
   {
       $payload = $request->validate([
           'notification' => 'required|string',
           'signature' => 'required|string',
       ]);
   
       $isValid = CybersourceHostedCheckout::verifyWebhook($payload['notification'], $payload['signature']);
       if ($isValid) {
           // Process the transaction (e.g., update order status)
       }
   }
   

Integration Tips

• Laravel Cashier Sync: Attach CyberSource transactions to Laravel Cashier subscriptions:

  $user->newSubscription('premium', $plan)
       ->create($token)
       ->syncPayment($response->transactionId);
  

• Local Testing: Use the test environment and CyberSource’s sandbox for mock transactions.

• Dynamic Fields: Extend the checkout with custom fields (e.g., shipping options):

  $checkoutUrl = CybersourceHostedCheckout::createCheckout([
      // ... default fields ...
      'customData' => [
          'shippingOption' => 'express',
          'giftMessage' => 'Happy Birthday!',
      ],
  ]);
  

Gotchas and Tips

Pitfalls

1. Signature Mismatch in Webhooks

   • Issue: Webhook verification fails due to incorrect secret or payload tampering.
   • Fix: Double-check the CYBERSOURCE_SECRET in .env and ensure the payload is unaltered. Use dd($payload) to debug.

2. Redirect URI Mismatch

   • Issue: CyberSource redirects to a returnUrl that doesn’t match your app’s routes.
   • Fix: Use absolute URLs (e.g., https://yourdomain.com/checkout/return) and verify the cancelUrl is accessible.

3. Currency/Amount Formatting

   • Issue: Transactions fail due to incorrect decimal places (e.g., 100.0 vs. 100.00).
   • Fix: Always pass amounts as floats with 2 decimal places:

     'amount' => (float) $cartTotal,
     

4. Idempotency

   • Issue: Duplicate transactions if the same orderId is reused.
   • Fix: Regenerate orderId for each checkout or implement idempotency keys in your backend.

Debugging

• Enable Logging Add to config/cybersource.php:

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

  Check storage/logs/laravel.log for raw API responses.

• Test Mode Quirks

  • Sandbox transactions always succeed but return test-specific transactionIds (e.g., 1234567890123456).
  • Use CYBERSOURCE_ENV=test for development; switch to live only after thorough testing.

Extension Points

1. Custom Templates Override CyberSource’s hosted page by extending the createCheckout payload:

   'template' => [
       'name' => 'custom_template',
       'data' => ['logoUrl' => asset('images/logo.png')],
   ],
   

2. Pre/Post-Processing Hooks Bind events in AppServiceProvider:

   public function boot()
   {
       CybersourceHostedCheckout::extend(function ($checkout) {
           $checkout->onBeforeRedirect(function ($payload) {
               // Modify payload (e.g., add tracking)
               $payload['customData']['trackingId'] = Str::uuid()->toString();
           });
       });
   }
   

3. Multi-Currency Support Dynamically set currency based on user locale:

   'currency' => app()->getLocale() === 'fr' ? 'EUR' : 'USD',
   

Pro Tip: Bookmark the CyberSource API Reference for field definitions and error codes (e.g., 104 = invalid merchant ID).