{"id":841317,"date":"2026-09-09T12:21:13","date_gmt":"2026-09-09T12:21:13","guid":{"rendered":"https:\/\/www.knowband.com\/blog\/?p=841317\/"},"modified":"2026-09-30T09:34:14","modified_gmt":"2026-09-30T09:34:14","slug":"prestashop-payment-gateway-integration","status":"publish","type":"post","link":"https:\/\/www.knowband.com\/blog\/prestashop-blog\/prestashop-payment-gateway-integration\/","title":{"rendered":"Integrating a Custom Payment Gateway in PrestaShop: Technical Requirements, API Flow, and Real-World OPC Challenges"},"content":{"rendered":"

Integrating a payment gateway into PrestaShop can look straightforward on paper.<\/span><\/p>\n

The gateway provides API documentation, sandbox credentials, authentication keys, callback URLs, and a few endpoints. The PrestaShop module then sends the payment request, receives the response, creates the order, and redirects the customer to the confirmation page.<\/span><\/p>\n

In a real PrestaShop store, however, the payment gateway is rarely working alone.<\/span><\/p>\n

The moment a store uses a One Page Checkout<\/a> (OPC) module such as SuperCheckout, multiple payment modules, custom payment flows, iframes, JavaScript-based payment methods, and additional checkout customizations can all interact with each other.<\/span><\/p>\n

This is where many payment integrations become difficult.<\/span><\/p>\n

During payment gateway compatibility work, we have encountered cases where a payment method worked perfectly with PrestaShop’s default checkout but behaved differently inside OPC. For example, a payment provider could display correctly on the standard checkout while options such as BLIK, bank selection, or BNPL disappeared inside SuperCheckout.<\/span><\/p>\n

The important lesson was that integrating a payment gateway is not only about making the API call work. It is about making the entire payment lifecycle work correctly inside the PrestaShop checkout.<\/span><\/p>\n

1.0 What Does a Custom Payment Gateway Actually Need?<\/strong><\/h2>\n

\"What<\/a><\/p>\n

At a high level, a PrestaShop payment integration needs to handle five things:<\/span><\/p>\n

    \n
  1. Display the payment method at checkout.<\/span><\/li>\n
  2. Send the customer or payment data to the gateway.<\/span><\/li>\n
  3. Receive and validate the gateway response.<\/span><\/li>\n
  4. Create or update the PrestaShop order correctly.<\/span><\/li>\n
  5. Return the customer to the appropriate confirmation or error page.<\/span><\/li>\n<\/ol>\n

    A typical payment module extends rather than the base class.<\/p>\n

    The payment module normally works with hooks such as:<\/p>\n

    The hook is responsible for making the payment method available to the checkout.<\/p>\n

    The hook handles what the customer sees after returning from the payment process.<\/p>\n

    For example:<\/span><\/p>\n

    public function hookPaymentOptions($params)\r\n{\r\nif (!$this->active || !$this->checkCurrency($params['cart'])) {\r\nreturn [];\r\n}\r\n\r\n$paymentOption = new PaymentOption();\r\n\r\n$paymentOption\r\n->setCallToActionText($this->l('Pay by Card'))\r\n->setAction(\r\n$this->context->link->getModuleLink(\r\n$this->name,\r\n'redirect',\r\n[],\r\ntrue\r\n)\r\n);\r\n\r\nreturn [$paymentOption];\r\n}<\/pre>\n
    The important point is that this hook should not simply assume that the payment method can always be displayed.<\/span><\/p>\n
    Currency, country, carrier, customer state, cart amount, module configuration, and gateway availability can all affect whether the payment method should be shown.<\/span><\/p>\n
    2.0 The Part That Changes Everything: OPC<\/strong><\/h2>\n
    The default PrestaShop checkout and a Prestashop One Page Checkout module do not necessarily process payment methods in exactly the same way.<\/span><\/p>\n
    This was one of the most important lessons from working with multiple payment modules.<\/span>
    \n<\/span><\/p>\n
    With the default checkout, a payment module generally controls its own payment option rendering and payment flow.<\/span><\/p>\n
    With an OPC, the checkout module becomes another layer between the payment module and the customer. That means the following can interact:<\/span><\/p>\n
    Customer<\/b>\r\n\u2193<\/span>\r\nOPC \/ SuperCheckout<\/b>\r\n\u2193<\/span>\r\nPayment options<\/b>\r\n\u2193<\/span>\r\nPayment module<\/b>\r\n\u2193<\/span>\r\nGateway API<\/b>\r\n\u2193<\/span>\r\nGateway response<\/b>\r\n\u2193<\/span>\r\nPayment module<\/b>\r\n\u2193<\/span>\r\nOPC \/ PrestaShop<\/b>\r\n\u2193<\/span>\r\nOrder confirmation<\/b><\/pre>\n
    A payment module can therefore be completely correct from an API perspective and still fail to behave correctly inside an OPC.<\/span><\/p>\n
    This is why payment compatibility testing should always include both:<\/span><\/p>\n