Getting Started

Minimal Setup

Installation

composer require clubmaster/quickpay

Add the bundle to config/bundles.php:

Clubmaster\QuickpayBundle\ClubmasterQuickpayBundle::class => ['all' => true],

Configuration Publish the default config:

php bin/console config:dump-reference ClubmasterQuickpayBundle

Update config/packages/clubmaster_quickpay.yaml with your Quickpay credentials:

clubmaster_quickpay:
    api_key: "your_api_key_here"
    secret_key: "your_secret_key_here"
    test_mode: true  # Set to false for production

First Use Case: Creating a Payment Inject the QuickpayGateway service into your controller/service:

use Clubmaster\QuickpayBundle\Gateway\QuickpayGateway;

public function __construct(private QuickpayGateway $quickpay) {}

public function createPayment(Request $request) {
    $payment = $this->quickpay->createPayment(
        1000, // Amount in smallest currency unit (e.g., 1000 DKK = 10 DKK)
        'DKK', // Currency
        'order_123', // Order ID
        'Customer Name', // Customer name
        'customer@example.com', // Customer email
        'https://your-site.com/payment/callback' // Callback URL
    );
    return new JsonResponse($payment->getPaymentUrl());
}

Implementation Patterns

Common Workflows

1. Handling Webhooks

Use the QuickpayWebhookHandler service to validate and process events:

use Clubmaster\QuickpayBundle\Event\WebhookEvent;
use Clubmaster\QuickpayBundle\Gateway\QuickpayWebhookHandler;

public function handleWebhook(Request $request, QuickpayWebhookHandler $handler) {
    $event = $handler->handle($request);
    if ($event->isValid()) {
        // Process payment event (e.g., capture, refund, cancellation)
        $this->processPaymentEvent($event);
    }
    return new Response('OK');
}

2. Capturing Payments

Capture a payment after authorization:

$capture = $this->quickpay->capturePayment(
    'payment_id_from_quickpay',
    1000 // Amount to capture (optional; defaults to authorized amount)
);

3. Refunding Payments

Refund a captured payment:

$refund = $this->quickpay->refundPayment(
    'payment_id_from_quickpay',
    500 // Amount to refund
);

4. Subscription Management

Create a subscription (if supported by the package):

$subscription = $this->quickpay->createSubscription(
    'customer_id',
    1000, // Price per period
    'month', // Billing period
    'product_name'
);

Integration Tips

Laravel-Specific Adjustments

Service Container Binding: Bind the QuickpayGateway to Laravel’s container in a service provider:

$this->app->bind(QuickpayGateway::class, function ($app) {
    return new QuickpayGateway(
        $app['config']['clubmaster_quickpay.api_key'],
        $app['config']['clubmaster_quickpay.secret_key'],
        $app['config']['clubmaster_quickpay.test_mode']
    );
});

Event Dispatching: Extend the bundle to dispatch Laravel events (e.g., PaymentCaptured) for decoupled handling:
```
// In your webhook handler
event(new PaymentCaptured($event->getPayment()));
```

Testing

Use test_mode: true in config to test without real transactions.

Mock the QuickpayGateway in PHPUnit:

$mockGateway = $this->createMock(QuickpayGateway::class);
$mockGateway->method('createPayment')->willReturn(new Payment('test_url'));
$this->app->instance(QuickpayGateway::class, $mockGateway);

Gotchas and Tips

Pitfalls

Webhook Validation:
- Always validate webhook signatures using QuickpayWebhookHandler. Skipping this risks processing fake events.
- Example of invalid signature handling:
```
if (!$event->isValid()) {
    throw new \RuntimeException('Invalid Quickpay webhook signature');
}
```
Currency and Amount Units:
- Quickpay expects amounts in the smallest currency unit (e.g., 10 DKK = 1000). Misconfiguration here causes failed payments.
- Validate currency codes against Quickpay’s supported currencies.
Idempotency:
- Quickpay may retry webhooks. Design your handlers to be idempotent (e.g., check if a payment already exists before processing).
Rate Limits:
- Quickpay has API rate limits. Cache responses for non-critical operations.
Deprecated Methods:
- The package is minimal (1 star, low maturity). Check the Quickpay API docs for breaking changes and update the bundle accordingly.

Debugging Tips

Enable Logging: Add logging to the QuickpayGateway constructor:

public function __construct(string $apiKey, string $secretKey, bool $testMode) {
    $this->logger = new \Monolog\Logger('quickpay');
    $this->logger->pushHandler(new \Monolog\Handler\StreamHandler('var/log/quickpay.log'));
}

Test Mode Quirks:
- Test mode payments expire after 1 hour. Use the same payment ID for retries within this window.
- Test mode uses a sandbox environment. Ensure your callback URLs point to a local/test server.

Error Handling:

Wrap API calls in try-catch blocks to handle QuickpayException:

try {
    $payment = $this->quickpay->createPayment(...);
} catch (QuickpayException $e) {
    $this->logger->error('Quickpay error: ' . $e->getMessage());
    throw new \RuntimeException('Payment failed. Please try again.');
}

Extension Points

Custom Payment Models:

Extend the bundle to map Quickpay responses to your domain models:

class PaymentMapper {
    public function mapToDomain(array $quickpayData): Payment {
        return new Payment(
            $quickpayData['id'],
            $quickpayData['amount'],
            // ...
        );
    }
}

Additional Gateway Features:
- Add support for Quickpay’s advanced features (e.g., 3D Secure, invoicing) by extending QuickpayGateway.

Laravel Notifications:

Integrate with Laravel Notifications to send payment status emails:

use Illuminate\Notifications\Notification;

class PaymentNotification extends Notification {
    public function toMail($notifiable) {
        return (new MailMessage)
            ->line('Payment captured: ' . $this->payment->id);
    }
}

Quickpay Laravel Package