PrestaShop 1.7 introduces a new payment API. Below, you’ll find information about how it works and also, how to migrate your module from PrestaShop 1.6 (and earlier) to PrestaShop 1.7.
The main reason why the change was needed is on the customer side: Now, there is only one button to validate the order, not one by payment module anymore.
The bankwire module is an example of how a payment module for PS 1.6 is migrated to PS 1.7 API.
A skeleton is also available on GitHub.
Please note that your module won’t be listed in payment methods admin page unless it is referenced in the official list. However you can still configure it through the Module Manager.
To make a payment module for PrestaShop 1.7, you’ll have to respect some elements:
Your class will have to extend PaymentModule.
You will need to declare the following namespace.
<?php
use PrestaShop\PrestaShop\Core\Payment\PaymentOption;
You’ll have to register the two following methods: hookPaymentOptions() & hookPaymentReturn() and register these hooks.
You must not have a submit button into your module’s HTML code. It will automatically be generated by PrestaShop.
In the hookPaymentOptions() method, you have to return an array of PaymentOption.
Here is a list of the PaymentOption class variables. They all have a getter and a setter and are accessible in the array sent to the front office template.
$callToActionText: The text displayed as the payment method name.$additionalInformation: Additional information to display to the customer. This is free HTML, and may be used by modules such as bankwire to display to which account the bank transfer should be made.$logo: The URL to a picture to display in the payment option selection widget.$action: The URL to which the request to process the payment must be made.$inputs: An associative array of additional parameters to use when sending the request to $action.$form: The custom HTML to display like a form to enter the credit card information.$iframe: The custom HTML containing an iframe with the payment confirmation widget for modules like ATOS.$moduleName: The name of the module.$binary: A boolean to set if the module form was generated by binaries and contains a submit button. It’s necessary to adapt the behavior.You can find a example module illustrating the four identified cases of payment modules on GitHub.
We have identified four cases of payment module:
: This is the most simple case where you could be (e.g.:Bankwire, Cheque). It’s a simple URL to call, then various information are displayed to the customer.
The minimal variables to set are `$callToActionText` and `$action`. You can check the `getOfflinePaymentOption()` method of *[paymentexample](https://github.com/PrestaShop/paymentexample)* to have an example.
: It’s a simple URL to call, then the payment is directly processed on the Payment Service Provider’s website (e.g.: PayPal, Paybox).
The minimal variables to set are `$callToActionText` and `$action`. The form will be sent by POST and you can add hidden inputs such as a token, by using `setInput()` method. You can check the `getExternalPaymentOption()` method of *[paymentexample](https://github.com/PrestaShop/paymentexample)* to have an example.
: You write your credit card number and all the required data directly on the merchant’s website (e.g.: Stripe).
The minimal variables to set are `$callToActionText` and `$form`. You can check the `getEmbeddedPaymentOption()` method of *[paymentexample](https://github.com/PrestaShop/paymentexample)* to have an example.
: The payment form is displayed on the merchant’s website, but inside an iframe.
The minimal variables to set are `$callToActionText` and `$additionalInformation`. You can check the `getIframePaymentOption()` method of *[paymentexample](https://github.com/PrestaShop/paymentexample)* to have an example.
We do have extra rules for Payment Modules as this type of modules require higher security. Note that there are some modules which create the Order with a pending order status during the payment processing (1), while others wait for the payment system’s approval to create it (2). But none of them create an order before the customer passed the payment service (bank, PayPal…).
Make sure you double check the id_cart before creating the order.
if (2), make sure the amount you use to validateOrder() comes from the external payment system. Do not use Cart->getOrderTotal();
For (2), when receiving a call to process the payment, make sure you double check the source of the call using a signature or a token. Those values must not be known of all.
You need to change the payment hook where your module is hooked on by paymentOption. It’s not a display hook anymore, so you must not use the $this->display() method to retrieve a template, but use the $this->context->smarty->fetch() method instead.
Then, implement the hookPaymentOptions() function to return an array of PaymentOption.
Next, you’ll need to identify the type of your payment module to know which variables are mandatory.
As you may read it above, you must not have a submit button into your module’s HTML code, because PrestaShop will automatically generate it. If you can’t remove the submit button from the form for some reasons (e.g.: the form is generated by binaries), we have implemented another way to make your module PrestaShop 1.7 compatible. But, note that this is NOT the recommended way to do it.
To do this, you’ll need to implement a supplementary hook: displayPaymentByBinaries. It’s made to display the payment form, and
it will replace the unique payment button in the checkout.
You’ll also need to set the $binary variable to true. It will adapt the behavior to hide the payment button and replace it by the form when the payment option is selected.
The params passed to the following hooks have been modified:
hookPaymentReturnhookDisplayOrderConfirmation| Key | Value |
|---|---|
| total_to_pay | Result of $order->getOrdersTotalPaid() |
| currency | Currency sign (string) |
| currencyObj | The loaded currency (Currency class) |
| objOrder | The current order object (Order class) |
| Key | Value |
|---|---|
| order | The current order object (Order class) |
Everything can be retrieved, for example:
<?php
$currency = new Currency($params['order']->id_currency);
$total_to_pay = $params['order']->getOrdersTotalPaid();