Getting Started

Minimal Setup

Installation:
```
composer require origammi/payment-bundle
```
Ensure your composer.json targets Symfony 2.8 or 3.4.

Enable the Bundle: Add to config/bundles.php (Symfony 3.4+):

return [
    // ...
    Origammi\PaymentBundle\AstinaPaymentBundle::class => ['all' => true],
];

Configure Parameters: Define provider-specific parameters in config/packages/astina_payment.yaml (or app/config/parameters.yml for Symfony 2.8):

astina_payment:
    datatrans:
        merchantid: "YOUR_MERCHANT_ID"
        serviceurl: "https://secure.datatrans.com/paypage/"
        authorizexmlurl: "https://secure.datatrans.com/payextras/authorize.fcgi"
        capturexmlurl: "https://secure.datatrans.com/payextras/capture.fcgi"
        sign: "YOUR_SIGN"
        sign2: "YOUR_SIGN2"
    # Repeat for other providers (paypal, saferpay, computop)

Service Configuration: Override the default service definition in config/services.yaml (or app/config/services.xml for Symfony 2.8):

services:
    astina_payment.provider:
        class: Astina\PaymentBundle\Provider\Datatrans\Provider
        arguments:
            $merchantId: "%env(ASTINA_DATATRANS_MERCHANTID)%"
            $serviceUrl: "%env(ASTINA_DATATRANS_SERVICEURL)%"
            # ... other arguments
            $logger: "@logger"

First Use Case: Use the PaymentManager to create a payment:

use Astina\PaymentBundle\Manager\PaymentManager;

class CheckoutController extends AbstractController
{
    public function checkout(PaymentManager $paymentManager)
    {
        $payment = $paymentManager->createPayment('datatrans', 100.00, 'EUR');
        $payment->setDescription('Product Purchase');
        $payment->setOrderId('ORDER_123');

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

Implementation Patterns

Core Workflow

Payment Creation: Use PaymentManager to instantiate a payment object for a specific provider:

$payment = $paymentManager->createPayment('paypal', 50.00, 'USD');
$payment->setCurrency('USD');
$payment->setReturnUrl($this->generateUrl('checkout_success'));

Redirect to Provider: For redirect-based flows (e.g., PayPal), use the generated URL:
```
return $this->redirect($payment->getPaymentUrl());
```

Handle Callback: After user returns, process the callback:

public function handleCallback(PaymentManager $paymentManager, Request $request)
{
    $payment = $paymentManager->createTransactionFromRequest($request);
    if ($payment->isSuccessful()) {
        // Process successful payment
    }
    return $this->render('checkout/callback.html.twig');
}

Direct API Calls: For non-redirect providers (e.g., Datatrans), call methods directly:
```
$result = $payment->authorize();
$payment->capture($result->getTransactionId());
```

Integration Tips

Symfony Forms: Bind payment fields to a form for user input:

$builder->add('cardNumber', TextType::class, [
    'attr' => ['autocomplete' => 'cc-number']
]);

Event Listeners: Subscribe to payment events (e.g., payment.success) for logging or notifications:

services:
    App\EventListener\PaymentListener:
        tags:
            - { name: kernel.event_listener, event: payment.success, method: onPaymentSuccess }

Testing: Use the testmode parameter for Saferpay or mock the PaymentManager in tests:

$this->paymentManager->expects($this->once())
    ->method('createPayment')
    ->willReturn($mockPayment);

Multi-Provider Support: Dynamically switch providers based on user selection or region:

$provider = $request->get('provider', 'datatrans');
$payment = $paymentManager->createPayment($provider, $amount, $currency);

Gotchas and Tips

Pitfalls

Deprecated Symfony 2.8: The bundle is unmaintained and lacks Symfony 5/6 support. Avoid in new projects unless absolutely necessary.
Breaking Changes:
- Saferpay v1.20: Version 3.0.0 requires username and terminalId parameters (previously optional).
- Computop URL Changes: Hardcoded URLs in older versions may break; update to the latest computop/paygate endpoint.
Logger Dependency: The logger argument is mandatory for all providers. Ensure it’s injected correctly:
```
arguments:
    $logger: "@logger"  # Not "@monolog.logger"
```
PayPal NVP API:
- The bundle uses deprecated PayPal NVP API (v53.0). Migrate to REST API for new projects.
- DoExpressCheckoutPayment may fail if PAYMENTREQUEST_0_AMT doesn’t match the original SetExpressCheckout amount.
Datatrans Signatures: sign and sign2 are case-sensitive and must match your Datatrans merchant configuration exactly.
Saferpay Test Mode:
- The testmode parameter was renamed from environment in v2.0.0. Ensure consistency:
```
# Correct (v2.0+)
astina_payment.saferpay.testmode: true
```
- Test API (https://test.saferpay.com) requires a separate test account (not shared with production).
Computop Limitations: Only authorization is implemented. Capture/refund requires custom logic or a newer provider.

Debugging Tips

Enable Logging: Configure Monolog to log payment requests/responses:

monolog:
    handlers:
        payment:
            type: stream
            path: "%kernel.logs_dir%/payment.log"
            level: debug

Raw Request/Response: For PayPal/Datatrans, inspect the raw data in the Payment object:
```
$payment->getRawResponse(); // After callback
```
Saferpay API Errors: Check the PaymentException for Saferpay-specific error codes (e.g., 100 for invalid credentials).
Symfony 3.4 Compatibility: If using Symfony 3.4, ensure flex-recuse is installed for autowiring:
```
composer require symfony/flex
```

Extension Points

Custom Providers: Extend Astina\PaymentBundle\Provider\AbstractProvider to add new gateways:

class StripeProvider extends AbstractProvider
{
    public function createPaymentUrl(): string
    {
        // Custom logic
    }
}

Override Services: Replace the default PaymentManager to add pre/post-processing:

services:
    astina_payment.manager:
        class: App\Service\CustomPaymentManager
        decorates: astina_payment.manager
        arguments:
            $innerManager: '@astina_payment.manager.inner'

Payment Events: Dispatch custom events in PaymentManager:

$dispatcher->dispatch(new PaymentEvent($payment, 'payment.created'));

Configuration Validation: Add validation to parameters.yml using Symfony’s validator:

astina_payment:
    datatrans:
        sign: "%env(string:ASTINA_DATATRANS_SIGN)%" # Enforce string type

Webhook Handling: For providers without callbacks (e.g., Stripe), implement a webhook controller:

public function handleWebhook(Request $request, PaymentManager $manager)
{
    $payment = $manager->createTransactionFromWebhook($request->getContent());
    // Process async payment
}

Payment Bundle Laravel Package