Payex Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require bsadnu/payex-bundle
   

   Enable it in config/bundles.php:

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

2. Configuration Publish the default config:

   php bin/console bsadnu:payex:install
   

   Update config/packages/bsadnu_payex.yaml with your PayEx credentials (e.g., merchant_id, test_mode, secret_key).

3. First Use Case: Redirect Payment Create a controller to initiate a payment:

   use Bsadnu\PayexBundle\Service\PayexService;
   
   class PaymentController extends AbstractController
   {
       public function createPayment(PayexService $payex): Response
       {
           $payment = $payex->createPayment(
               '123', // Order ID
               1000,  // Amount (in lowest currency unit, e.g., 1000 = 10.00 SEK)
               'SEK', // Currency
               'https://your-site.com/payment/callback' // Callback URL
           );
   
           return $this->redirect($payment->getPaymentUrl());
       }
   }
   

4. Callback Handling Define a route for PayEx’s callback (e.g., /payment/callback) and verify the response:

   public function handleCallback(PayexService $payex, Request $request): Response
   {
       $response = $payex->verifyCallback($request->getContent());
       if ($response->isSuccessful()) {
           // Process successful payment (e.g., update order status)
       }
       return new Response('OK');
   }
   

Implementation Patterns

Workflows

1. Payment Flow

   • Initiate: Use PayexService::createPayment() to generate a redirect URL.
   • Redirect: Send the user to PayEx’s payment page.
   • Callback: PayEx posts back to your endpoint; verify with verifyCallback().
   • Post-Processing: Handle success/failure (e.g., update database, send notifications).

2. Recurring Payments Use createRecurringPayment() for subscriptions:

   $recurring = $payex->createRecurringPayment(
       'sub_123',
       500,
       'SEK',
       'monthly',
       'https://your-site.com/recurring/callback'
   );
   

3. Refunds Refund a payment via:

   $payex->createRefund('payment_id_123', 500, 'SEK');
   

Integration Tips

• Symfony Forms: Bind payment fields to a form for user input (e.g., card details for direct payments).
• Events: Listen to payex.payment.created or payex.payment.callback events for custom logic.
• Logging: Enable debug mode in config to log requests/responses for troubleshooting:

  bsadnu_payex:
      debug: true
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Callback Verification

   • Never trust PayEx’s callback without verifying the signature. Use verifyCallback() and check:

     $response = $payex->verifyCallback($rawContent);
     if (!$response->isValidSignature()) {
         throw new \RuntimeException('Invalid callback signature!');
     }
     

   • Test callbacks: In test mode, PayEx sends test callbacks. Use test_mode: true in config.

2. Amount Handling

   • PayEx expects amounts in the lowest currency unit (e.g., 10.00 SEK = 1000).
   • Rounding errors: Ensure your backend matches PayEx’s precision (e.g., use bcmath for floats).

3. Timeouts

   • PayEx callbacks may retry. Implement idempotency (e.g., store payment_id in DB before processing).
   • Set a timeout for your callback route (e.g., 30 seconds) to avoid hanging.

4. Deprecated Methods

   • The bundle is last updated in 2018. Some PayEx API endpoints may have changed. Check PayEx’s API docs for breaking changes.

5. Direct Payments (Tokenization)

   • If using direct payments (without redirect), ensure you handle PCI compliance (e.g., tokenize cards via PayEx’s JS library).

Debugging

• Enable Debug Mode:

  bsadnu_payex:
      debug: true
  

  Logs requests/responses to var/log/payex.log.

• Test Mode: Use PayEx’s test environment (test_mode: true) to simulate payments. Test cards:

  • Success: 4111111111111111 (Visa)
  • Failure: 4000000000000002 (Declined)

• Common Errors:

  Error	Cause	Fix
  Invalid signature	Callback tampering or wrong secret.	Verify secret_key in config.
  Payment not found	Wrong payment_id or test mode issue.	Check PayEx dashboard for test payments.
  Amount mismatch	Currency/amount mismatch.	Ensure amounts match PayEx’s precision.
  Callback URL unreachable	Incorrect URL in PayEx config.	Test the callback URL manually.

Extension Points

1. Custom Responses Extend Bsadnu\PayexBundle\Response\PaymentResponse to add custom fields:

   class CustomPaymentResponse extends PaymentResponse
   {
       public function getCustomField(): string
       {
           return $this->data['custom_field'] ?? '';
       }
   }
   

   Override the service to use your class.

2. Event Listeners Subscribe to events for custom logic:

   // config/services.yaml
   services:
       App\EventListener\PayexListener:
           tags:
               - { name: kernel.event_listener, event: payex.payment.created, method: onPaymentCreated }
   

3. API Versioning If PayEx updates their API, fork the bundle and override the PayexClient class to adapt to new endpoints.

4. Multi-Currency Support Dynamically set currency based on user locale:

   $currency = $user->getPreferredCurrency(); // e.g., 'EUR'
   $payex->createPayment($orderId, $amount, $currency, $callbackUrl);
   

Configuration Quirks

• Secret Key: Ensure the secret_key in bsadnu_payex.yaml matches PayEx’s merchant settings.
• Callback URL: Must be HTTPS and publicly accessible. Test it with curl:

  curl -X POST -H "Content-Type: application/json" --data '{"payment":"..."}' https://your-site.com/payment/callback
  

• Test vs. Live: Always test in test_mode before switching to live. Use PayEx’s test cards.