Payex Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require develit-ab/payex-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       DevelitAB\PayexBundle\PayexBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference DevelitAB\PayexBundle\Resources/config/services.yml
   

   Update config/packages/develit_ab_payex.yaml with your PayEx credentials:

   develit_ab_payex:
       merchant_id: "your_merchant_id"
       secret_key: "your_secret_key"
       test_mode: true # Set to false for live
   

3. First Use Case: Redirect Payment Use the PayexGateway service to create a payment:

   use DevelitAB\PayexBundle\Service\PayexGateway;
   
   public function createPayment(PayexGateway $payex, Request $request)
   {
       $payment = $payex->createPayment(
           $request->request->get('amount'),
           $request->request->get('currency'),
           $request->request->get('description'),
           $request->request->get('callback_url')
       );
       return new RedirectResponse($payment->getPaymentUrl());
   }
   

Implementation Patterns

Core Workflows

1. Payment Creation & Redirect

   • Use PayexGateway::createPayment() for one-click payments.
   • Handle the redirect URL ($payment->getPaymentUrl()) in your frontend.
   • Store the paymentId in your DB for later reference.

2. Server-Side Callback Handling

   • PayEx sends POST requests to your callback_url with payment status.
   • Validate the signature (see PayexGateway::validateCallback()).
   • Example callback controller:

     public function handleCallback(PayexGateway $payex, Request $request)
     {
         if ($payex->validateCallback($request)) {
             $payment = $payex->getPaymentFromCallback($request);
             // Process payment (e.g., update order status)
         }
         return new Response('OK');
     }
     

3. Recurring Payments

   • Use PayexGateway::createRecurringPayment() for subscriptions.
   • Store the recurringPaymentId and handle renewal callbacks.

4. Refunds

   • Use PayexGateway::createRefund() for partial/full refunds:

     $refund = $payex->createRefund(
         $paymentId,
         $amount,
         $currency,
         $description
     );
     

Integration Tips

• Database Schema: Store paymentId, status, and amount in your orders table.
• Logging: Log all paymentId and callback responses for debugging.
• Testing: Use test_mode: true with PayEx’s sandbox environment.
• Frontend: Use the paymentUrl to redirect users; never expose the paymentId directly.

Gotchas and Tips

Common Pitfalls

1. Callback Validation

   • Gotcha: Always validate the callback signature (validateCallback()). Skipping this exposes you to fraud.
   • Tip: Use PayexGateway::getPaymentFromCallback() to parse the response safely.

2. Test Mode Quirks

   • Gotcha: Test mode uses sandbox credentials but still requires valid callback URLs.
   • Tip: Test with PayEx’s sandbox test cards (e.g., 4111111111111111).

3. Currency & Amount

   • Gotcha: PayEx expects amounts in minor units (e.g., 100.00 → 10000 for SEK).
   • Tip: Multiply amounts by 100 before passing to the bundle.

4. Idempotency

   • Gotcha: PayEx does not natively support idempotency keys. Regenerate paymentId for retries.
   • Tip: Store the paymentId in your DB to avoid duplicate payments.

5. Deprecated Methods

   • Gotcha: The bundle is outdated (last release 2018). Some PayEx API methods may have changed.
   • Tip: Check PayEx’s API docs for breaking changes.

Debugging Tips

• Enable Logging: Configure Monolog to log DevelitAB\PayexBundle for callback debugging.
• Inspect Raw Responses: Use PayexGateway::getLastResponse() to debug failed callbacks.
• PayEx Dashboard: Monitor transactions in the PayEx Merchant Portal.

Extension Points

1. Custom Callback Logic

   • Extend DevelitAB\PayexBundle\Service\PayexGateway to add custom payment status handlers.
   • Example:

     $payex->onPaymentSuccess(function ($payment) {
         // Custom logic (e.g., send email)
     });
     

2. Webhook Handling

   • For advanced use, replace the callback controller with a Symfony Messenger handler or API platform event.

3. Multi-Currency Support

   • Override PayexGateway to handle dynamic currency conversion if needed.