Getting Started

Minimal Setup

Install the Bundle Add the package via Composer:

composer require antilop/paybox-bundle

return [
    // ...
    Antilop\Bundle\PayboxBundle\PayboxBundle::class => ['all' => true],
];

Configure Paybox Create config/packages/paybox.yml (Symfony 5+) or app/config/paybox.yml (older versions):

paybox:
    parameters:
        production: false  # Set to `true` for live environment
        site: 'YOUR_SITE_ID'
        rank: 'YOUR_RANK'
        login: 'YOUR_LOGIN'
        hmac:
            key: 'YOUR_HMAC_KEY'

First Use Case: Payment Request Inject the PayboxClient service and trigger a payment:

use Antilop\Bundle\PayboxBundle\Client\PayboxClient;

class PaymentController extends AbstractController
{
    public function initiatePayment(PayboxClient $paybox): Response
    {
        $payment = $paybox->createPayment([
            'amount' => 1000, // Amount in cents
            'currency' => '978', // EUR
            'order_id' => 'ORDER_123',
            'return_url' => $this->generateUrl('payment_return'),
            'cancel_url' => $this->generateUrl('payment_cancel'),
            'notification_url' => $this->generateUrl('payment_notification'),
        ]);

        return $this->redirect($payment->getPaymentUrl());
    }
}

Implementation Patterns

Core Workflows

Payment Initiation Use PayboxClient::createPayment() to generate a payment URL. Pass an associative array with:

Required: amount, currency, order_id, return_url, cancel_url, notification_url.
Optional: description, customer_email, customer_ip, template (if configured).

$payment = $paybox->createPayment([
    'amount' => 5000,
    'currency' => '978',
    'order_id' => 'INV-456',
    'return_url' => '/payment/success',
    'cancel_url' => '/payment/failed',
    'notification_url' => '/payment/webhook',
    'template' => 'YOUR_TEMPLATE_ID', // If using Paybox templates
]);

Handling Callbacks Paybox sends notifications to notification_url. Validate the HMAC signature before processing:

use Antilop\Bundle\PayboxBundle\Validator\PayboxValidator;

public function handleNotification(Request $request, PayboxValidator $validator): Response
{
    if (!$validator->validateNotification($request)) {
        return new Response('Invalid signature', 403);
    }

    $data = $request->request->all();
    // Process payment status (e.g., update database)
    return new Response('OK');
}

Refunds Use PayboxClient::createRefund() for partial/full refunds:

$refund = $paybox->createRefund('ORDER_123', 2500); // Refund 25€

Subscription Management For recurring payments, use PayboxClient::createSubscription():

$subscription = $paybox->createSubscription([
    'amount' => 1000,
    'currency' => '978',
    'order_id' => 'SUB_789',
    'cycle' => 'monthly',
    'trial_days' => 7,
]);

Integration Tips

Symfony Forms: Bind Paybox fields to a form for user input (e.g., card details if using hosted payment pages).

Event Listeners: Subscribe to paybox.notification events to decouple validation logic:

// config/services.yaml
services:
    App\EventListener\PayboxListener:
        tags:
            - { name: kernel.event_listener, event: paybox.notification, method: onNotification }

Testing: Use the production: false flag to test against Paybox’s sandbox environment.
Logging: Enable debug mode in paybox.yml to log requests/responses:
```
paybox:
    debug: true
```

Gotchas and Tips

Pitfalls

HMAC Validation

Issue: Silent failures if HMAC validation fails in production.

Fix: Always log failed validations and return 403 explicitly:

if (!$validator->validateNotification($request)) {
    $this->addFlash('error', 'Payment notification failed validation');
    return $this->redirectToRoute('home');
}

Amount Formatting
- Issue: Paybox expects amounts in cents (e.g., 1000 for €10.00). Forgetting this causes silent failures.
- Fix: Validate amounts server-side before passing to Paybox.
URL Requirements
- Issue: return_url, cancel_url, and notification_url must be absolute URLs (include https://).
- Fix: Use generateUrl() with full domain or hardcode URLs in production.
Template Dependencies
- Issue: The bundle mentions "templates" in the config, but Paybox’s template system is undocumented here. Templates may require additional setup in your Paybox merchant dashboard.
- Fix: Test template-based payments in sandbox first.
Deprecated Methods
- Issue: The bundle is experimental (last release 2021). Some methods may change or break.
- Fix: Check the Paybox API docs for breaking changes and update locally if needed.

Debugging Tips

Enable Debug Mode Add debug: true to paybox.yml to log raw requests/responses to var/log/paybox.log.
Sandbox Testing
- Use production: false to test payments without real transactions.
- Paybox sandbox credentials are documented here.
Common Errors
- 401 Unauthorized: Invalid site, rank, or login in config.
- 400 Bad Request: Missing required fields (e.g., order_id).
- 500 Server Error: HMAC mismatch (check hmac.key and request data).
Extension Points
- Custom Validators: Extend PayboxValidator to add business logic (e.g., fraud checks).
- Payment Models: Map Paybox responses to your domain models:
```
$paymentStatus = $paybox->getPaymentStatus('ORDER_123');
$this->paymentRepository->updateFromPaybox($paymentStatus);
```

Configuration Quirks

Environment Variables Avoid hardcoding sensitive data (e.g., hmac.key). Use Symfony’s param bag or .env:

# config/packages/paybox.yml
paybox:
    parameters:
        hmac:
            key: '%env(PAYBOX_HMAC_KEY)%'

Caching The bundle doesn’t cache Paybox responses by default. For high-volume apps, cache getPaymentStatus() results:

$cacheKey = 'paybox_status_' . $orderId;
$status = $cache->get($cacheKey);
if (!$status) {
    $status = $paybox->getPaymentStatus($orderId);
    $cache->set($cacheKey, $status, 300); // Cache for 5 mins
}

Asynchronous Notifications If notification_url is slow to respond, Paybox may retry. Implement idempotency (e.g., track processed order_ids in a database).

Paybox Bundle Laravel Package