Payment Paypoint Hosted Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require barbondev/payment-paypoint-hosted-bundle:dev-master
   

   Update autoloader:

   composer dump-autoload
   

2. Bundle Registration Add to config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 3/2):

   Barbondev\Payment\PayPointHostedBundle\BarbondevPaymentPayPointHostedBundle::class => ['all' => true],
   

3. Routing Include in config/routes.yaml:

   barbondev_payment_paypoint_hosted:
       resource: "@BarbondevPaymentPayPointHostedBundle/Resources/config/routing.xml"
       prefix: /
   

4. Configuration Set PayPoint credentials in config/packages/barbon_payment_paypoint_hosted.yaml:

   barbon_payment_paypoint_hosted:
       merchant: "YOUR_MERCHANT_ID"
       gateway_url: "https://your-paypoint-gateway-url"
   

5. First Use Case Create a payment method in a controller:

   use JMS\Payment\CoreBundle\Payment\PaymentMethod;
   use JMS\Payment\CoreBundle\Payment\PaymentMethodInterface;
   
   public function checkoutAction(Request $request)
   {
       $paymentMethod = new PaymentMethod();
       $paymentMethod->setGateway('paypoint_hosted');
       $paymentMethod->setAmount(1000); // Amount in cents
       $paymentMethod->setCurrency('GBP');
   
       // Redirect to PayPoint
       return $this->get('jms_payment_payum')->createPayment($paymentMethod);
   }
   

Implementation Patterns

Core Workflow

1. Payment Initiation Use the jms_payment_payum service to create a PayPoint payment:

   $payment = $this->get('jms_payment_payum')->createPayment($paymentMethod);
   $payment->setRedirectUrl($this->generateUrl('payment_success'));
   $payment->setNotifyUrl($this->generateUrl('payment_notify'));
   

2. Handling Redirects PayPoint redirects back to your notify route after payment. Process the response:

   public function notifyAction(Request $request)
   {
       $payment = $this->get('jms_payment_payum')->getPayment($request->query->get('payment_id'));
       $payment->execute();
       return new Response('OK');
   }
   

3. Status Checks Verify payment status in a controller:

   $payment = $this->get('jms_payment_payum')->getPayment($paymentId);
   if ($payment->isCompleted()) {
       // Payment succeeded
   }
   

Integration Tips

• Order Management Attach payment to an order entity:

  $order->setPayment($payment);
  $this->getDoctrine()->getManager()->persist($order);
  

• Webhooks Use PayPoint’s IPN (Instant Payment Notification) for server-side validation:

  public function ipnAction(Request $request)
  {
      $payment = $this->get('jms_payment_payum')->getPayment($request->request->get('payment_id'));
      $payment->execute(); // Validate signature and status
  }
  

• Testing Use PayPoint’s sandbox environment in config:

  barbon_payment_paypoint_hosted:
      gateway_url: "https://sandbox.paypoint.net/..."
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides Ensure merchant and gateway_url are correctly set. PayPoint may reject requests with invalid credentials.

2. Redirect URLs PayPoint requires redirect_url and notify_url to be HTTPS. Test locally with ngrok if needed.

3. Amount Precision PayPoint expects amounts in cents (e.g., 1000 for £10.00). Use number_format($amount * 100, 0, '', '') to avoid floating-point errors.

4. IPN Validation PayPoint sends IPN requests with a signature parameter. Validate it server-side:

   $signature = $request->request->get('signature');
   $expectedSignature = hash_hmac('sha256', $request->getContent(), 'YOUR_SECRET_KEY');
   if (!hash_equals($signature, $expectedSignature)) {
       throw new \RuntimeException('Invalid IPN signature');
   }
   

Debugging

• Logs Enable Payum logging in config/packages/monolog.yaml:

  handlers:
      payment:
          type: stream
          path: "%kernel.logs_dir%/payment.log"
          level: debug
          channels: ["payment"]
  

• PayPoint Test Mode Use PayPoint’s test cards (e.g., 4111111111111111) to debug without real transactions.

Extension Points

1. Custom Fields Add extra PayPoint parameters via PaymentMethod:

   $paymentMethod->setDetails([
       'customer_email' => 'user@example.com',
       'customer_name' => 'John Doe',
   ]);
   

2. Post-Processing Extend the BarbondevPaymentPayPointHostedBundle to add custom logic after payment:

   // In a service
   $payment->postExecute(function ($payment) {
       $this->sendConfirmationEmail($payment);
   });
   

3. Gateway Configuration Override default PayPoint settings via dependency injection:

   services:
       barbondev_payment_paypoint_hosted.gateway:
           arguments:
               - "%barbon_payment_paypoint_hosted.gateway_url%"
               - "%barbon_payment_paypoint_hosted.merchant%"
               - "@some_custom_service" # Inject your own logic