Creating a PrestaShop 1.7 Payment Module

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.

Requirements

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.

   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.

How to generate your PaymentOption

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.

PaymentOption types

You can find a example module illustrating the four identified cases of payment modules on GitHub.

We have identified four cases of payment module in which you can be:

• Offline:
  
  • 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 to have an example.
• External:
  
  • 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_ to have an example.
• Embedded:
  
  • 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 to have an example.
• Iframe:
  
  • 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 to have an example.

Migrating from 1.6 to 1.7

How-To

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.

What if I can’t remove the submit button?

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 PrestaShp 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.

Hooks

The parameters passed to the following hooks have been modified:

• hookPaymentReturn
• hookDisplayOrderConfirmation

AFTER

Everything can be retrieved, for example:

$currency = new Currency($params['order']->id_currency);
$total_to_pay = $params['order']->getOrdersTotalPaid();

Real life example

See the bankwire module for an example of how we updated a simple 1.6 module to 1.7: https://github.com/PrestaShop/bankwire/pull/18