Relay Mono Connector Payunity Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

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

   Register the bundle in config/app.php under providers:

   DigitalBlueprint\RelayMonoConnectorPayUnityBundle\PayUnityBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="DigitalBlueprint\RelayMonoConnectorPayUnityBundle\PayUnityBundle" --tag="config"
   

   Update config/payunity.php with your PayUnity API credentials (e.g., api_key, merchant_id).

3. First Use Case: Payment Webhook Define a Relay route in config/relay.php to handle PayUnity webhooks:

   'routes' => [
       'payunity_webhook' => [
           'path' => '/payunity/webhook',
           'method' => 'POST',
           'handler' => \App\Http\Controllers\PayUnityWebhookController::class,
       ],
   ],
   

   Create a controller to process the webhook payload:

   namespace App\Http\Controllers;
   use DigitalBlueprint\RelayMonoConnectorPayUnityBundle\Services\PayUnityService;
   
   class PayUnityWebhookController extends Controller {
       public function __invoke(PayUnityService $payUnityService, Request $request) {
           $payload = $request->json()->all();
           return $payUnityService->handleWebhook($payload);
       }
   }
   

Implementation Patterns

Workflow: Payment Processing

1. Initiate Payment Use the PayUnityService to create a payment request:

   $payment = $payUnityService->createPayment([
       'amount' => 100.00,
       'currency' => 'USD',
       'description' => 'Order #12345',
       'customer_email' => 'user@example.com',
   ]);
   

   Return the payment->id to redirect the user to PayUnity’s checkout.

2. Webhook Handling Implement a Relay route (as above) to listen for PayUnity’s payment.succeeded or payment.failed events. Validate the payload using PayUnity’s signature:

   public function handleWebhook(PayUnityService $payUnityService, Request $request) {
       $payload = $request->json()->all();
       if (!$payUnityService->validateWebhook($payload)) {
           abort(403, 'Invalid webhook signature');
       }
       // Process the event (e.g., update order status)
       return response()->json(['status' => 'success']);
   }
   

3. Refunds/Voids Use the service to manage post-payment actions:

   $payUnityService->refundPayment($paymentId, ['amount' => 50.00]);
   // or
   $payUnityService->voidPayment($paymentId);
   

Integration Tips

• Relay API Gateway: Leverage Relay’s routing to centralize webhook handling. Example:

  // In a Relay middleware or service
  $relay = app(\DigitalBlueprint\RelayBundle\Relay::class);
  $relay->route('payunity_webhook', $request);
  

• Event Dispatching: Extend the bundle to dispatch Laravel events (e.g., PaymentSucceeded) after processing webhooks:

  event(new PaymentSucceeded($payload['payment_id'], $payload['amount']));
  

• Logging: Use Laravel’s logging to track PayUnity interactions:

  \Log::info('PayUnity payment created', ['payment_id' => $payment->id]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Service

   • PayUnity’s shutdown means this bundle is unsupported. Use at your own risk. Consider migrating to alternatives like Stripe or PayPal via Relay’s mono-connector.
   • Mitigation: Fork the repository to maintain compatibility or replace PayUnity entirely.

2. Webhook Validation

   • The bundle assumes PayUnity’s webhook signature validation is handled internally. If PayUnity’s API changes (e.g., new signature format), the validateWebhook() method may break.
   • Debugging: Enable Relay’s debug mode (RELAY_DEBUG=true) to inspect raw webhook payloads:

     if (config('relay.debug')) {
         \Log::debug('Raw PayUnity payload', $payload);
     }
     

3. Configuration Overrides

   • The bundle uses config('payunity') for settings. Overrides in config/payunity.php may conflict with Relay’s mono-connector defaults.
   • Tip: Explicitly set all required keys (e.g., api_key, endpoint) to avoid silent failures.

4. Error Handling

   • PayUnity’s API may return generic errors (e.g., 400 Bad Request). Wrap service calls in try-catch:

     try {
         $payment = $payUnityService->createPayment($data);
     } catch (\DigitalBlueprint\RelayMonoConnectorPayUnityBundle\Exceptions\PayUnityException $e) {
         \Log::error('PayUnity error: ' . $e->getMessage());
         abort(500, 'Payment processing failed');
     }
     

Extension Points

1. Custom Webhook Events Extend the PayUnityService to support additional PayUnity events (e.g., subscription.updated):

   // In a service provider
   $payUnityService->extendWebhookHandler('subscription.updated', function ($payload) {
       // Custom logic
   });
   

2. Relay Middleware Add middleware to Relay’s pipeline to pre-process PayUnity requests:

   // In a Relay service provider
   $relay->addMiddleware(\App\Middleware\ValidatePayUnityRequest::class);
   

3. Testing Mock the PayUnityService in tests using Laravel’s HTTP testing:

   $response = $this->post('/payunity/webhook', ['payload' => $data]);
   $response->assertStatus(200);
   

Debugging Tips

• Relay Logs: Check storage/logs/laravel.log for Relay/PayUnity-related entries.
• Payload Dumping: Use Laravel’s dd() or dump() to inspect $request->json()->all() during webhook testing.
• API Testing: Use tools like Postman to manually test PayUnity’s API endpoints before integrating with Relay.

```markdown
## Configuration Quirks
1. **Endpoint Overrides**
   The bundle defaults to PayUnity’s production endpoint. For testing, override in `config/payunity.php`:
   ```php
   'endpoint' => 'https://sandbox.payunity.com/api/v1',

2. Signature Secret Ensure the signature_secret in config/payunity.php matches PayUnity’s webhook settings. Mismatches will cause 403 errors.

3. Relay Route Conflicts Avoid naming Relay routes that conflict with Laravel’s built-in routes (e.g., /payunity/webhook vs. /payments/webhook). Use unique paths.