[ADD] ecommerce: add payment_payfort configuration

ecommerce/shopper_experience.rst

@@ -6,6 +6,7 @@ Get paid
    :titlesonly:
 
    shopper_experience/payment
+   shopper_experience/payfort
    shopper_experience/paypal
    shopper_experience/authorize
    shopper_experience/wire_transfer

ecommerce/shopper_experience/payfort.rst

@@ -0,0 +1,171 @@
+==============================
+Configure your Payfort account
+==============================
+
+Payfort is an Amazon company providing payment services, mostly in the MENA region. It is fully
+supported by Odoo, making classical and tokenization payment flows possible with little
+configuration.
+
+It is strongly advised to use a test account in addition to your real account; that way, you can
+test configuration changes safely in a copy of your instance before making any change in your
+production environment.
+
+Installing the Payfort integration module
+=========================================
+
+The Payfort integration was added after the release of Odoo 13 for our own internal needs - we
+decided to make this integration standard so that all our customers might use it.
+
+This means that your Odoo source code must be up-to-date for the module to be available. If your
+Odoo instance was created prior to the addition of the module in the code, you will need to update
+the list of available modules.
+
+To do so, follow these steps:
+
+#. Enable the Developer Mode by going to :menuselection:`Settings --> Activate the developer mode`
+#. Go to :menuselection:`Apps --> Update Apps List` and confirm the operation
+
+The Payfort module is now visible in the list of applications and can be installed from there.
+If you want the Payfort integration to be visible in the list of available payment providers without
+first installing the module, you can update the ``payment`` base module:
+
+.. warning::
+   Updating a module can lead to a small downtime for your database. Make sure to check if the
+   update works correctly in a duplicate database first.
+
+#. Go to :menuselection:`Apps`
+#. Remove the *Apps* filter from the search menu
+#. Search for the ``payment`` module (*Payment Acquirer*)
+#. Update that module
+
+Payfort will now be visible in the list of available acquirers, independently of its installation
+status.
+
+Create a Payfort account
+========================
+
+Creating a Payfort account can take some time, as you will need to get in touch with them through
+their `online form <https://www.payfort.com/get-started/>`_ first. Depending on your expected usage
+of Odoo, you will need to require some specific options for your account.
+
+The most basic configuration will require the *Redirection* channel. An advanced integration,
+allowing customers to save their card for future payments (e.g. to process recurring charges in the
+Subscription application or to allow your customer to pay easily through your eCommerce with saved
+cards), will require the channels *Recurring* and *Merchant Page*.
+
+Supported Payment Methods
+=========================
+
+Payfort supports multiple payment options; all major credit cards are supported,
+as well as local payment methods such as Mada, Knet or Meeza. However, these
+local payment methods do not support tokenization (saving payment data for future
+usage, e.g. through the Subscription application).
+
+If you configure Payfort to use the *Payment from Odoo* payment flow (which is
+required if you plan to use tokenization), your customers will not be able to pay
+using these local payment methods. If you plan for a simple eCommerce integration
+without the use of subscriptions, using the *Redirection to the acquirer website*
+payment flow is recommended, as it supports more payment methods and will make
+payment more convenient for your customers.
+
+Credit card support is always available, independently of the payment flow
+selection.
+
+Settings in Payfort
+===================
+
+Security Parameters
+-------------------
+
+First, you need to configure your security parameters. To do so, connect to your
+Payfort account and go to :menuselection:`Integration Settings --> Secuirty Settings`.
+
+This page contains your Merchant Identifier, Access Code and cryptographic passphrases
+for securing communications between Odoo and Payfort. Set the *SHA Type* field to
+*SHA-256*, and fill in the mandatory fields. You will need to input these in Odoo
+later on. Your SHA passphrases should be difficult to guess and not too short (using
+a password generator to create strong passphrases is strongly advised).
+
+You can set up *Origin IP* and *Origin URL* restrictions, though that may not always
+be advisable. Odoo Online instances can change IP without prior notice, for example in
+case of hardware retirement or planned maintenance. The origin URL might not always
+be the same, especially if you enable support for multiple websites in Odoo.
+If you are unsure about these settings, leave them empty.
+
+You can see here an example configuration of the security settings in Payfort:
+
+.. image:: media/payfort_security_settings.png
+    :align: center
+
+Notification and Return URLs
+----------------------------
+
+Payfort provides a notification mechanism that will notify Odoo of new payments
+and of updates in existing payments. These notifications act as a fallback to
+make sure that all payments status are correct in Odoo, even if your customer closes
+their browser window or lose connectivity during payment confirmation.
+
+For every payment channel activated on your Payfort account, you will need to specify
+the notification URL. To do so, go to :menuselection:`Integration Settings --> Technical Setting`
+and configure every payment channel with the notification URL *<BaseUrl>/payment/payfort/notify*
+(e.g. ``https://my-ecommerce.odoo.com/payment/payfort/notify``).
+
+The URL is identical for the *Notification URL* and
+*Direct Transaction Feedback*. In the case of the redirection channel, you will also
+need to specify a *Redirection URL*: *<BaseUrl>/payment/payfort/return* (e.g. 
+``https://my-ecommerce.odoo.com/payment/payfort/return``). Make
+sure to set *Send Response Parameters* to ``Yes``.
+
+The *Response Type* field
+should be set to ``JSON`` and the *Return URL Type* to ``POST``. Downgrading
+the CVC is advised as it does not impact communication with Odoo and will limit
+the amount of sensitive information that will be included in the technical logs.
+
+.. note::
+   Not all fields may be available depending on the payment channel you are
+   configuring.
+
+You can see an example configuration for the Redirection channel here:
+
+.. image:: media/payfort_url_config.png
+   :align: center
+
+Settings in Odoo
+================
+
+Activation
+----------
+
+* Activate Payfort in Odoo from :menuselection:`Website or Accounting --> Settings -->
+  Payment Acquirers`.
+* Enter your Payfort security settings in the credentials tab: **Merchant Identifier**,
+  **Access Code**, **SHA Request Phrase** and **SHA Response Phrase**.
+* Choose your payment flow; note that the *Payment from Odoo* payment flow is only compatible with
+  credit card payments.
+* Finalize the configuration in the Configuration tab: set country restrictions, website
+  restrictions (if you have enabled support for multiple websites) and/or payment icons for local
+  payment options (only for *Redirection to the acquirer website* payment flows).
+* Set the Payfort provider to the correct status (*Enabled* for a production account, *Test* for a
+  test account)
+
+.. note::
+   Payment Icons are only there to indicate to your customers which payment options are available.
+   Enabling support for these options should be done in your Payfort account. Icons for the local
+   payment options are available but are not active by default.
+
+Go live!
+========
+
+Payfort is now available in your payment form available in eCommerce, Sales, Subscription and
+Invoicing apps. Your customers will get back to a confirmation page in Odoo once the payment is
+processed.
+
+
+.. note::
+   *(for integrators only)* Be aware that the Payfort integration makes use of ``iframe`` elements;
+   your web server configuration should allow iframes with the ``sameorigin`` value of the
+   ``X-Frame-Options`` header of Odoo pages.
+
+.. seealso::
+   - :doc:`payment`
+   - :doc:`payment_acquirer`

ecommerce/shopper_experience/payment.rst

@@ -24,11 +24,12 @@ Redirect your customers to payment platforms to collect money effortless
 and track the payment status (call-back).
 Odoo supports more and more platforms over time: 
 
-* `Paypal <paypal.html>`__
-* Ingenico
-* Authorize.net
 * Adyen
+* :doc:`Authorize.net <authorize>`
 * Buckaroo
+* Ingenico
+* :doc:`Payfort <payfort>`
+* :doc:`Paypal <paypal>`
 * PayUmoney
 * Sips
 * Stripe