Getting Started

Minimal Steps to Begin

Installation Add the bundle via Composer:

composer require cedriclombardot/ogone-payment-bundle:dev-master

$bundles[] = new Cedriclombardot\OgonePaymentBundle\CedriclombardotOgonePaymentBundle();

Configuration Configure config.yml with your Ogone credentials and design preferences:

cedriclombardot_ogone_payment:
    secret:
        shaInKey: "your_sha_in_key"
        shaOutKey: "your_sha_out_key"
        algorithm: "sha512"
    general:
        PSPID: "your_psp_id"
        currency: "EUR"
        language: "en_EN"
    design:
        title: "Payment Gateway"
        bgColor: "#4e84c4"
        # ... other design settings

First Use Case Redirect a user to Ogone’s payment page:

use Cedriclombardot\OgonePaymentBundle\Builder\TransactionBuilder;

$transaction = $this->get('ogone.transaction_builder')
    ->order()
        ->setAmount(10.00)
        ->setCurrency('EUR')
        ->setPSPReference('ORDER_123')
        ->setShopperEmail('user@example.com')
        ->setShopperLanguage('en')
        ->setShopperCountry('BE')
    ->build();

return $this->redirect($transaction->getPaymentUrl());

Implementation Patterns

Common Workflows

1. Transaction Creation and Redirection

Use the TransactionBuilder to construct a transaction and redirect users to Ogone’s payment page:

$transaction = $this->get('ogone.transaction_builder')
    ->order()
        ->setAmount($order->getTotal())
        ->setPSPReference('ORDER_' . $order->getId())
        ->setShopperEmail($order->getCustomerEmail())
        ->setShopperIP($request->getClientIp())
        ->addParameter('CNC', 'Y') // Enable 3D Secure if needed
    ->build();

return $this->redirect($transaction->getPaymentUrl());

2. Handling Ogone Callback

Ogone sends a callback to your application after payment. Use the OgoneCallbackListener to process it:

// In your controller or event subscriber
$callback = $this->get('ogone.callback_handler')->handleCallback($request);

if ($callback->isSuccessful()) {
    $order = $this->findOrderByPSPReference($callback->getPSPReference());
    $order->markAsPaid();
    $order->save();
}

3. Alias Management

Create and manage payment aliases for recurring payments:

$alias = $this->get('ogone.alias_builder')
    ->create()
        ->setPSPReference('ALIAS_' . $user->getId())
        ->setAmount(50.00)
        ->setCurrency('EUR')
        ->setShopperEmail($user->getEmail())
    ->build();

return $this->redirect($alias->getPaymentUrl());

4. Feedback Management

Retrieve transaction status or feedback:

$feedback = $this->get('ogone.feedback_builder')
    ->getFeedback()
        ->setPSPReference('ORDER_123')
        ->setShopperEmail('user@example.com')
    ->build();

$response = $feedback->getResponse();

Integration Tips

1. Service Injection

Inject the builder services directly into your controllers or services:

use Cedriclombardot\OgonePaymentBundle\Builder\TransactionBuilderInterface;

class PaymentController extends Controller
{
    private $transactionBuilder;

    public function __construct(TransactionBuilderInterface $transactionBuilder)
    {
        $this->transactionBuilder = $transactionBuilder;
    }
}

2. Event Listeners

Use Symfony’s event system to handle Ogone callbacks or transaction status updates:

# config/services.yml
services:
    app.ogone.callback_listener:
        class: AppBundle\EventListener\OgoneCallbackListener
        arguments: ['@ogone.callback_handler']
        tags:
            - { name: kernel.event_listener, event: ogone.callback, method: onOgoneCallback }

3. Testing

Mock the OgoneClient service for unit tests:

$mockClient = $this->createMock(OgoneClient::class);
$mockClient->method('getPaymentUrl')->willReturn('http://test-payment-url.com');

$this->container->set('ogone.client', $mockClient);

Gotchas and Tips

Pitfalls

1. SHA Key Mismatch

Issue: If shaInKey or shaOutKey is incorrect, Ogone callbacks will fail with a SHA mismatch error.
Fix: Double-check your configuration in config.yml and ensure keys match those provided by Ogone.

2. Callback Verification

Issue: Always verify the callback signature using shaOutKey before processing. The bundle provides tools, but manual verification is recommended for critical systems:

$expectedSignature = hash_hmac('sha512', $callbackData, $this->getParameter('ogone.secret.shaOutKey'));
if (!hash_equals($expectedSignature, $request->get('SHAResult'))) {
    throw new \RuntimeException('Invalid Ogone callback signature');
}

3. PSPReference Uniqueness

Issue: Ogone requires PSPReference to be unique for each transaction. Reusing references can cause duplicate transactions or failed payments.
Fix: Use a combination of a static prefix (e.g., ORDER_) and a unique ID (e.g., database auto-increment ID).

4. 3D Secure (CNC)

Issue: Enabling 3D Secure (CNC=Y) may cause additional redirects and require extra handling in your flow.
Fix: Test thoroughly with 3D Secure enabled and ensure your callback endpoint handles the additional steps.

5. Currency and Language

Issue: Ogone may reject transactions if the currency or language is not supported for your PSPID.
Fix: Verify supported currencies/languages with Ogone’s documentation and adjust your configuration accordingly.

Debugging Tips

1. Enable Debug Mode

Ogone provides detailed feedback in their responses. Log the raw response for debugging:

$feedback = $this->get('ogone.feedback_builder')->getFeedback()->setPSPReference('ORDER_123')->build();
$response = $feedback->getResponse();
\Log::debug('Ogone Feedback Response:', ['response' => $response->getData()]);

2. Test in Sandbox

Use Ogone’s test environment (PSPID for testing) before going live. The bundle does not differentiate between live and test modes, so ensure your configuration is switched accordingly.

3. Check Ogone Logs

Ogone provides transaction logs in their merchant interface. Cross-reference your application logs with Ogone’s logs to identify discrepancies.

Extension Points

1. Custom Parameters

Add custom parameters to transactions or aliases:

$transaction = $this->get('ogone.transaction_builder')
    ->order()
        ->setAmount(10.00)
        ->addParameter('CustomField1', 'CustomValue')
    ->build();

2. Override Services

Extend or replace bundle services (e.g., OgoneClient) by defining your own service in services.yml:

services:
    ogone.client:
        class: AppBundle\Service\CustomOgoneClient
        arguments: ['@ogone.http_client', '%ogone.secret.shaInKey%', '%ogone.secret.shaOutKey%']

3. Custom Callback Handling

Extend the OgoneCallbackListener to add custom logic:

class CustomOgoneCallbackListener extends OgoneCallbackListener
{
    public function onOgoneCallback(GetResponseEvent $event)
    {
        parent::onOgoneCallback($event);
        // Add custom logic here
    }
}

4. Batch Operations (Future)

Monitor the repository for updates on batch operations (e.g., refunds or captures) and integrate them into your workflows.

Configuration Quirks

1. Algorithm Parameter

Ensure the algorithm in config.yml matches the one used by Ogone (e.g., sha512). Changing it mid-transaction can cause signature verification failures.

2. Design Parameters

Ogone’s design parameters (e.g., bgColor, fontType) must be valid CSS

Ogone Payment Bundle Laravel Package