Epay Symfony Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require chargily/epay-symfony
   

   Add to config/bundles.php:

   \Chargily\SymfonyBundle\ChargilySymfonyBundle::class => ['all' => true],
   

2. Configure API Keys Add to config/services.yaml:

   parameters:
       chargily.api_key: "%env(CHARGILY_API_KEY)%"
       chargily.secret_key: "%env(CHARGILY_SECRET_KEY)%"
   

3. First Use Case: Redirect to Payment Page Inject ChargilyClient service and call createPayment():

   use Chargily\SymfonyBundle\Service\ChargilyClient;
   
   public function paymentAction(Request $request, ChargilyClient $chargily)
   {
       $payload = [
           'client' => 'user123',
           'client_email' => 'user@example.com',
           'invoice_number' => 'INV-1001',
           'amount' => 100.00,
           'mode' => 'CIB', // or 'CARD'
           'back_url' => $request->getSchemeAndHttpHost() . '/payment/success',
           'webhook_url' => $request->getSchemeAndHttpHost() . '/webhook/epay',
       ];
   
       $response = $chargily->createPayment($payload);
       return new RedirectResponse($response['payment_url']);
   }
   

Implementation Patterns

Core Workflows

1. Payment Initiation Use ChargilyClient::createPayment() to generate a payment link. Always include:

   • back_url: Redirect after payment (success/failure).
   • webhook_url: Endpoint to handle asynchronous updates (e.g., POST /webhook/epay).

2. Webhook Handling Implement a Symfony controller to process webhook payloads:

   public function webhookAction(Request $request, ChargilyClient $chargily)
   {
       $payload = json_decode($request->getContent(), true);
       $signature = $request->headers->get('X-Chargily-Signature');
   
       if ($chargily->validateWebhook($payload, $signature)) {
           // Process payment status (e.g., update database)
           $this->handlePaymentUpdate($payload);
           return new Response('OK', 200);
       }
       return new Response('Invalid', 403);
   }
   

3. Refunds and Cancellations Use ChargilyClient::refund() or ChargilyClient::cancel():

   $chargily->refund('INV-1001', 50.00); // Partial refund
   $chargily->cancel('INV-1001');        // Full cancellation
   

Integration Tips

• Environment Variables: Store api_key and secret_key in .env (e.g., CHARGILY_API_KEY=your_key).
• Symfony Forms: Bind payment fields to a form for user input:

  $builder->add('amount', MoneyType::class, ['currency' => 'EGP']);
  $builder->add('mode', ChoiceType::class, ['choices' => ['CIB' => 'CIB', 'CARD' => 'Card']]);
  

• Logging: Wrap API calls in a service to log responses/errors:

  $logger->info('Payment response', ['data' => $response]);
  

Gotchas and Tips

Pitfalls

1. Webhook Validation

   • Issue: Failing to validate webhook signatures may expose your app to spoofing.
   • Fix: Always use ChargilyClient::validateWebhook():

     if (!$chargily->validateWebhook($payload, $signature)) {
         throw new \RuntimeException('Invalid webhook signature');
     }
     

2. URL Encoding

   • Issue: back_url/webhook_url must be absolute and URL-encoded.
   • Fix: Use Symfony’s UrlGenerator:

     $backUrl = $this->generateUrl('payment_success', [], UrlGeneratorInterface::ABSOLUTE_URL);
     

3. Mode Selection

   • Issue: Hardcoding mode (e.g., 'CIB') may break if Chargily changes supported modes.
   • Fix: Fetch supported modes via API or use a config array:

     # config/services.yaml
     parameters:
         chargily.supported_modes: ['CIB', 'CARD', 'MADA']
     

4. Idempotency

   • Issue: Retried webhooks may cause duplicate processing.
   • Fix: Track processed webhooks in a database (e.g., webhook_signature as a unique key).

Debugging

• Enable API Debugging: Set debug: true in config to log raw API responses:

  chargily:
      debug: true
  

• Test with Sandbox: Use Chargily’s test API keys (mode: 'TEST' in payload) before going live.

Extension Points

1. Custom Payloads Extend the payload with Chargily’s additional fields:

   $payload['custom_data'] = json_encode(['user_id' => 123]);
   

2. Event Dispatching Trigger Symfony events after payment/webhook processing:

   $event = new PaymentProcessedEvent($payload);
   $this->eventDispatcher->dispatch($event, PaymentEvents::POST_PROCESS);
   

3. Monetary Precision Ensure amount uses PHP’s bcmath for precision (e.g., 100.00 instead of 100).