Cmi Pay Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require cmiecom/cmi-pay-bundle
   

   Ensure routes.xml is included in config/routes.yaml:

   _cmi_pay:
       resource: '@CmiPayBundle/Resources/config/routes.xml'
   

2. Configure CMI Gateway Add CMI credentials to your .env or config/packages/cmi_pay.yaml:

   cmi_pay:
       merchant_id: 'YOUR_MERCHANT_ID'
       merchant_password: 'YOUR_PASSWORD'
       test_mode: true # Set to false for production
   

3. First Use Case: Render Payment Form Use the default route /cmi/requestpayment to render the payment form:

   // In your controller
   return $this->render('your_template.html.twig', [
       'cmi_pay_form' => $this->get('cmi_pay.form_builder')->buildForm($orderId, $amount, $currency)
   ]);
   

Implementation Patterns

Workflows

1. Payment Request Flow

   • Frontend: Render the form using CmiPayFormBuilder (e.g., in Twig):

     {{ form_start(cmi_pay_form) }}
         {{ form_widget(cmi_pay_form) }}
         <button type="submit">Pay with CMI</button>
     {{ form_end(cmi_pay_form) }}
     

   • Backend: Submit the form to /cmi/requestpayment, which redirects the user to CMI’s payment page.

2. Callback Handling

   • Configure a route for CMI’s callback (e.g., /cmi/callback):

     <route id="cmi_pay_callback" path="/cmi/callback" controller="cmi.pay.controller::callback" />
     

   • Validate the callback in your controller:

     public function callback(Request $request) {
         $validator = $this->get('cmi_pay.validator');
         if ($validator->validateCallback($request)) {
             // Process successful payment (e.g., update order status)
         }
         return new Response('Callback processed');
     }
     

3. Order Integration

   • Pass order details (ID, amount, currency) to CmiPayFormBuilder:

     $form = $this->get('cmi_pay.form_builder')->buildForm(
         $order->getId(),
         $order->getAmount(),
         $order->getCurrency()
     );
     

Integration Tips

• Symfony Forms: Extend the default form with custom fields if needed by overriding CmiPayFormBuilder.
• Order State Management: Use Symfony’s state machine (e.g., symfony/workflow) to transition order states post-callback.
• Logging: Log callback responses for debugging:

  $this->get('logger')->info('CMI Callback', ['data' => $request->request->all()]);
  

Gotchas and Tips

Pitfalls

1. Callback Validation

   • Always validate CMI’s callback signature using CmiPayValidator to prevent fraud:

     if (!$validator->validateCallback($request)) {
         throw new \RuntimeException('Invalid CMI callback');
     }
     

   • Test callbacks in sandbox mode (test_mode: true) before going live.

2. Redirect URLs

   • Ensure okUrl (success) and failUrl (failure) in the form are absolute URLs (e.g., https://yourdomain.com/payment/success).
   • Use Symfony’s UrlGeneratorInterface for dynamic URLs:

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

3. Deprecated Package

   • The last release is from 2019. Verify compatibility with your Symfony/Laravel version (though this is a Symfony bundle).
   • Fork or extend the bundle if critical features are missing.

Debugging

• Test Mode: Enable test_mode: true to simulate transactions without real payments.
• Logs: Check Symfony’s var/log/dev.log for CMI API errors.
• CMI Sandbox: Test with CMI’s sandbox environment (credentials provided by CMI).

Extension Points

1. Custom Form Fields Override the form builder service:

   # config/services.yaml
   CmiPayBundle\Form\CmiPayFormBuilder:
       arguments:
           - '@form.factory'
           - '@cmi_pay.default_options'
       tags: ['cmi_pay.form_builder']
   

   Extend CmiPayFormBuilder to add fields like customer_email.

2. Webhook Handling For async notifications, create a custom controller to handle CMI’s webhook payloads.

3. Refunds/Voids The bundle doesn’t support these out-of-the-box. Implement via CMI’s API directly or extend the bundle.