Relay Mono Connector Campusonline Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package to your Laravel project via Composer:

   composer require dbp/relay-mono-connector-campusonline-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayMonoConnectorCampusonlineBundle\DigitalBlueprintRelayMonoConnectorCampusonlineBundle::class => ['all' => true],
   ];
   

2. Publish Configuration Publish the default configuration to customize API endpoints, credentials, and behavior:

   php artisan vendor:publish --provider="DigitalBlueprint\RelayMonoConnectorCampusonlineBundle\DigitalBlueprintRelayMonoConnectorCampusonlineBundle" --tag="config"
   

   Edit the published config at config/relay_mono_connector_campusonline.php.

3. First Use Case: Payment Processing Use the connector to initiate a CampusOnline payment via Relay’s Mono bundle:

   use DigitalBlueprint\RelayMonoConnectorCampusonlineBundle\Service\CampusOnlinePaymentService;
   
   $paymentService = app(CampusOnlinePaymentService::class);
   $payment = $paymentService->createPayment([
       'amount' => 100.00,
       'currency' => 'EUR',
       'reference' => 'ORDER-12345',
       'metadata' => ['user_id' => 1],
   ]);
   

   Check the documentation for request/response structures.

Implementation Patterns

Core Workflows

1. Payment Initiation

   • Use CampusOnlinePaymentService to create payments, refunds, or captures.
   • Example for refunds:

     $paymentService->refundPayment($paymentId, ['reason' => 'Customer request']);
     

2. Webhook Handling

   • CampusOnline may send asynchronous notifications. Register a webhook endpoint in your routes/api.php:

     Route::post('/campusonline/webhook', [CampusOnlineWebhookController::class, 'handle']);
     

   • Implement CampusOnlineWebhookController to validate and process events (e.g., payment.succeeded).

3. Integration with Relay Mono

   • The bundle extends Relay’s Mono bundle. Ensure your RelayMonoBundle is configured to route CampusOnline-specific requests:

     # config/relay_mono.yaml
     connectors:
         campusonline:
             enabled: true
             service_id: 'campusonline-connector'
     

4. Logging and Debugging

   • Enable debug mode in config to log raw API requests/responses:

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

   • Use Laravel’s logging facade to trace connector interactions:

     \Log::debug('CampusOnline payment request', ['data' => $requestData]);
     

Common Patterns

• Retry Logic: Wrap API calls in a retry mechanism (e.g., using spatie/laravel-retryable) for transient failures.
• Idempotency: Use the idempotency_key in requests to avoid duplicate processing.
• Event Dispatching: Trigger custom events (e.g., PaymentProcessed) after connector operations:

  event(new PaymentProcessed($payment));
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Ensure config/relay_mono_connector_campusonline.php is merged correctly with environment variables (e.g., CAMPUSONLINE_API_KEY).
   • Fix: Use config('relay_mono_connector_campusonline.api_key') to avoid hardcoding.

2. Webhook Validation

   • CampusOnline webhooks require HMAC signature verification. The bundle provides a validator, but ensure your endpoint:
     • Rejects requests with invalid signatures.
     • Uses the CampusOnlineWebhookValidator service:

       $validator = app(CampusOnlineWebhookValidator::class);
       if (!$validator->isValid($request)) {
           abort(403, 'Invalid webhook signature');
       }
       

3. Rate Limiting

   • CampusOnline may throttle requests. Implement exponential backoff in your retry logic:

     $this->retry(3, function () use ($paymentService) {
         return $paymentService->createPayment($data);
     }, 1000); // 1-second delay
     

4. Currency/Amount Formatting

   • CampusOnline expects amounts in minor units (e.g., 100.00 → 10000 for EUR cents).
   • Tip: Use a helper or accessor to convert:

     $amountInCents = (int) ($amount * 100);
     

Debugging Tips

• Enable API Debugging: Set 'debug' => true in config to log raw API calls.
• Test with Sandbox: Use CampusOnline’s sandbox environment (configured via config['sandbox'] = true).
• Inspect Responses: Dump the full response object for errors:

  \Log::error('CampusOnline error', [
      'response' => $response->getContent(),
      'status'  => $response->getStatusCode(),
  ]);
  

Extension Points

1. Custom Services

   • Extend CampusOnlinePaymentService to add domain-specific logic:

     class CustomCampusOnlineService extends CampusOnlinePaymentService {
         public function customPaymentFlow(array $data) {
             // ...
         }
     }
     

   • Bind it in a service provider:

     $this->app->bind(CampusOnlinePaymentService::class, CustomCampusOnlineService::class);
     

2. Event Listeners

   • Listen for CampusOnlinePaymentCreated or CampusOnlineWebhookReceived events to extend functionality:

     public function handle(CampusOnlinePaymentCreated $event) {
         // Update your CRM or send notifications
     }
     

3. Custom Webhook Handlers

   • Override the default webhook handler by binding a custom controller:

     $this->app->bind(
         CampusOnlineWebhookController::class,
         CustomCampusOnlineWebhookController::class
     );
     

Configuration Quirks

• Environment Variables: Prefix CampusOnline-specific vars with CAMPUSONLINE_ (e.g., CAMPUSONLINE_API_KEY).
• Default Values: The bundle provides defaults (e.g., timeout = 30 seconds). Adjust in config if needed.
• SSL Verification: Disable only for testing ('verify_ssl' => false), never in production.

```markdown
## Additional Notes for Laravel Developers
- **Service Container**: The bundle leverages Laravel’s DI container. Inject dependencies explicitly (e.g., `HttpClient`, `Logger`) for testing.
- **Testing**: Use `RelayMonoConnectorCampusonlineBundleTestCase` as a base for unit tests to mock HTTP clients.
- **Queue Jobs**: Offload long-running operations (e.g., webhook processing) to queues:
  ```php
  dispatch(new ProcessCampusOnlineWebhook($payload));

• API Versioning: Monitor CampusOnline’s API changes. Update the bundle’s client config if versioning is required.