Checkout Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require checkout-bundle/checkout:dev-master
   

   (Note: Use dev-master due to outdated releases; prefer direct GitHub dependency if possible.)

2. Register Bundle In config/app.php (Laravel 5.5+) or AppKernel.php (Laravel <5.5):

   'providers' => [
       // ...
       Checkout\PaymentBundle\CheckoutPaymentBundle::class,
   ],
   

3. Publish Config

   php artisan vendor:publish --provider="Checkout\PaymentBundle\CheckoutPaymentBundle"
   

   (Edit config/checkout.php for API keys, endpoints, etc.)

4. Route Integration Add to routes/web.php:

   Route::prefix('checkout')->group(function () {
       require __DIR__.'/vendor/checkout-bundle/checkout/src/Checkout/PaymentBundle/Resources/config/routing.yml';
   });
   

5. First Use Case Trigger a payment in a controller:

   use Checkout\PaymentBundle\Service\CheckoutService;
   
   public function initiatePayment(CheckoutService $checkout)
   {
       $response = $checkout->createPaymentSession([
           'amount' => 1000, // cents
           'currency' => 'EUR',
           'success_url' => route('payment.success'),
           'failure_url' => route('payment.failure'),
       ]);
       return redirect($response->getRedirectUrl());
   }
   

Implementation Patterns

Core Workflows

1. Payment Initiation

   • Use CheckoutService to create sessions:

     $session = $checkout->createPaymentSession($params);
     

   • Attach metadata (e.g., order ID):

     $session->setMetadata(['order_id' => 123]);
     

2. Webhook Handling

   • Register a route for /checkout/webhook and validate signatures:

     public function handleWebhook(Request $request, CheckoutService $checkout)
     {
         if (!$checkout->validateWebhook($request)) {
             abort(403);
         }
         $event = $checkout->parseWebhook($request);
         // Process event (e.g., capture, refund)
     }
     

3. Subscription Management

   • Create subscriptions via:

     $subscription = $checkout->createSubscription([
         'amount' => 2000,
         'interval' => 'month',
         'customer' => $customerId,
     ]);
     

4. Service Integration

   • Laravel Cashier: Use CheckoutService as a custom driver by extending CashierServiceProvider.
   • Queues: Dispatch webhook processing to queues:

     dispatch(new ProcessWebhook($event))->onQueue('checkout');
     

Laravel-Specific Tips

• Service Container Binding Bind the service manually if autowiring fails:

  $this->app->bind(CheckoutService::class, function ($app) {
      return new CheckoutService($app['config']['checkout']);
  });
  

• Middleware for API Keys Protect routes with middleware to validate API keys:

  Route::middleware(['checkout.auth'])->group(function () {
      // Protected routes
  });
  

• Testing Use CheckoutService mocks in PHPUnit:

  $mock = Mockery::mock(CheckoutService::class);
  $mock->shouldReceive('createPaymentSession')->andReturn(new PaymentSession());
  $this->app->instance(CheckoutService::class, $mock);
  

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The package targets Checkout.com’s classic API (discontinued in 2022). Use the official PHP SDK for new projects.
   • Classic API lacks features like 3D Secure 2.0 or SEPA Instant.

2. Configuration Quirks

   • API Key Format: Ensure keys are base64-encoded in config/checkout.php:

     'secret_key' => base64_encode('your_secret_key'),
     

   • Endpoint URLs: Hardcoded in the bundle. Override via config:

     'api_url' => env('CHECKOUT_API_URL', 'https://api.classic.checkout.com'),
     

3. Webhook Validation

   • Signature Mismatches: Always validate webhooks:

     if (!$checkout->validateWebhook($request, $request->header('X-Signature'))) {
         // Reject
     }
     

   • Idempotency: Use idempotency_key in requests to avoid duplicate processing.

4. Error Handling

   • HTTP Errors: Wrap API calls in try-catch:

     try {
         $response = $checkout->createPaymentSession($params);
     } catch (\Checkout\PaymentBundle\Exception\ApiException $e) {
         Log::error($e->getMessage(), ['error_code' => $e->getCode()]);
         abort(500);
     }
     

Debugging

• Enable Logging Add to config/logging.php:

  'channels' => [
      'checkout' => [
          'driver' => 'single',
          'path' => storage_path('logs/checkout.log'),
          'level' => 'debug',
      ],
  ],
  

  Then configure the service to use the channel:

  $checkout = new CheckoutService($config, new \Monolog\Logger('checkout'));
  

• API Request Inspection Extend CheckoutService to log raw requests:

  protected function doRequest($method, $uri, $params)
  {
      Log::debug('Checkout Request', [
          'method' => $method,
          'uri' => $uri,
          'params' => $params,
      ]);
      return parent::doRequest($method, $uri, $params);
  }
  

Extension Points

1. Custom Payment Methods Extend Checkout\PaymentBundle\Model\Payment to add fields:

   class CustomPayment extends Payment
   {
       protected $customField;
   
       public function setCustomField($value)
       {
           $this->customField = $value;
           return $this;
       }
   }
   

2. Event Dispatching Listen for payment events via Laravel’s event system:

   // In a service provider
   $checkout->on('payment.succeeded', function ($event) {
       event(new PaymentSucceeded($event->getPayment()));
   });
   

3. Testing Environment Use the sandbox endpoint in .env:

   CHECKOUT_API_URL=https://sandbox.classic.checkout.com
   CHECKOUT_SECRET_KEY=your_sandbox_key