PrestaShop

The Wajub module adds three payment options to a PrestaShop 8.1 or 9 store: Mobile Money and Card, each with Wajub's payment form inside the checkout, and Other payment methods, which takes the payer to Wajub's payment page for whatever else your account offers. It creates the order when the customer places it, settles it from Wajub's webhook, and refunds it both ways. A payment counts for what it collected, the customer pays the rest, and Sandbox and Live never mix.

Requirements

The module has no dependency: its API client is its own, and the zip ships nothing else.

Install the module

1. 1

   Upload the zip

   In the back office, Modules, Module Manager, Upload a module, then pick wajub.zip, from PrestaShop Addons or from Wajub. The zip holds one folder, wajub/.

2. 2

   Open its settings

   Configure opens the module's page, in four tabs: Connection, Payment methods, Appearance and Webhooks. PrestaShop gives that page to the SuperAdmin and to the profile of the employee who installed the module; Advanced Parameters, Team, Permissions gives it to others, under Payment, Wajub.

3. 3

   Connect, then test

   Connect the shop to your account (below), place a test order, then switch to Live.

The module adds two order states, Awaiting Wajub payment and Partially paid with Wajub. An order paid in full moves to PrestaShop's Payment accepted.

Connect your Wajub account

The shop needs one secret key per environment. Let Wajub create it with Connect with Wajub, or paste your own.

Connect with Wajub

Click Connect Sandbox or Connect Live (Reconnect once a key is saved) on the Connection tab. The shop shows a code and opens the Dashboard's approval page in a new tab: check that the code is the same, choose the environment, full access or a restricted key (the permissions the module needs, payments, refunds and webhooks, are ticked), and how long the key lasts, 90 days or No expiry, then click Authorize. The shop collects the key once, checks it as it checks a pasted key, saves it encrypted and registers the webhook with it. The key never reaches the browser.

To connect, the shop sends the Dashboard its name and domain, the environment asked for, the client type prestashop, a hash of its address and the permissions it needs. Any app can use the same exchange: see Connect your app to Wajub.

When a connected key expires

A key that lasts 90 days stops working on its date, which the Connection tab shows. From 14 days before it:

• every page of the back office shows Your Wajub key expires soon., then Your Wajub key has expired., to the employees who may change the module's settings, for the key each shop pays with, with a link to connect again (see Back-office alerts);
• the shop's e-mail address (Shop Parameters, Contact) gets one e-mail per key, Sandbox or Live, in the shop's default language. The module's scheduled task sends it, or the first page of the back office that shows the notice. A copy of the shop at another address sends none.

Choose No expiry for a store whose checkout must not stop.

Paste your keys

Open Paste keys instead on the Connection tab, and paste the keys from the Dashboard: sk_test. or rk_test. for Sandbox, sk. or rk. for Live. Each key is checked with Wajub before it is saved, and the page shows only its last characters afterwards. A live key pasted in the Sandbox field is refused.

Sandbox and Live

Each environment pays with its own key only. Sandbox without a sandbox key takes no payment at all, even with a live key saved, and the Connection tab says so. The module refuses to switch to Live without a live key, asks you to confirm before it does, and keeps a live key it would need while Live is selected.

A payment is read, cancelled and refunded with the key of the environment it was made in, whichever environment the shop uses now. A refund of an order paid in the other environment is refused.

While the shop takes test payments, the header of every page of the back office shows Wajub · Sandbox, a link to the Connection tab, to the employees who may open the module's settings. On a shop the public uses (debug mode off) that still takes test payments, the back office also shows Wajub is in Sandbox.: see Back-office alerts.

Register the webhook

Register automatically, on the Webhooks tab, finds or creates the shop's endpoint in your Wajub account, subscribes it to the events below, and saves its signing secret. An endpoint that already has the shop's address is kept, and given the events it lacks. Get a new signing secret renews the secret. Connect with Wajub registers the endpoint too. When an update of the module listens to more events, it adds them to the endpoint the shop registered, and keeps the others.

The event catalogue describes each one.

The tab shows the shop's webhook address, https://example.com/module/wajub/webhook (or index.php?fc=module&module=wajub&controller=webhook without friendly URLs), the last delivery the shop accepted, and, when deliveries are refused, why and what to do. To set it up by hand, add that address in the Dashboard, Developers, Webhooks, with the events above, and paste its signing secret in the tab.

Wajub cannot reach a shop on your own computer: test it with wajub listen --forward-to and the shop's webhook address, from the CLI. Live webhooks need an https:// address.

The checkout

Mobile Money and Card

Each option shows Wajub's payment form inside its payment box, in your theme's font, colours and rounding. Appearance, Payment form, forces a light or dark form. A Mobile Money payer types the number to pay with and picks their operator from a list with its logo, the number's own operator already chosen (a setting, on the Payment methods tab, finds it from the number instead), then approves the payment on their phone. A card payer enters their card, with 3-D Secure when the bank asks.

As soon as an option is selected, the shop prepares a payment for the cart, before the order exists: the amount, the currency, the option's kind and the cart, nothing about the payer. Place order creates the order, then activates that payment for it, with the payer's name, e-mail address and phone number. A payment prepared and never activated is charged to no one and expires.

Without JavaScript, or when the form does not load within 15 seconds, the payer pays on Wajub's payment page, which offers that option's kind only.

Other payment methods

The payer goes to Wajub's payment page, which offers only what your account has beyond Mobile Money and cards: PayPal, wallets and the like. The option shows only when something is left.

Each option shows only when your account offers it for the cart's currency, total and country (GET /payments/options, kept 10 minutes, or 1 minute when Wajub does not answer). When Wajub does not answer, Mobile Money and Card show, and Other payment methods does not.

Placing the order

The order is created when the customer places it, in Awaiting Wajub payment. Its confirmation e-mail waits until it is paid. While a Mobile Money payment waits for the payer's approval, the order confirmation page says what to do on the phone, follows the payment and updates by itself.

A payment declined, cancelled or expired, or Use another payment method, cancels the order and gives the cart back, with a message, unless a payment of the order may still go through.

When a payment does not cover the order

A payment counts toward its order for what it collected. One that covers the total pays the order; one short of it (an instalment payment closed early, an order changed after the payment started) moves it to Partially paid with Wajub, and the customer pays the rest with Pay the rest, on the order confirmation page and in Order details of their account. The new payment, named after the order (Order #XKBKNABJK-2), asks for what is left only. An instalment payment still open is resumed when it can be, or closed keeping what it collected.

The merchant reads on the order when a second payment went through, or a payment in another currency.

One-page checkout modules

The module is tested with PrestaShop's own checkout. A one-page checkout module redraws the payment options after each change of address or carrier, and has a button of its own; the module copes as long as the options keep PrestaShop's markup:

• each option keeps its name="payment-option" radio, and the Wajub box ([data-wajub-fields]) and form (form[data-wajub-form]) stay in their option's block;
• the module watches the page: options drawn again get their form mounted again, on the same prepared payment. A module may also call window.WajubCheckout.sync() once it has drawn them;
• whatever submits a Wajub option's form, PrestaShop's Place order, a module's button, or a script calling submit(), goes through the same steps.

When none of that holds, the payer pays on Wajub's payment page, and the order is placed all the same.

Orders in the back office

The Wajub payment panel of an order lists its payments (status, method, amount, what counted, environment, a link to the Dashboard), its refunds and the module's notes. Check status reads the payment from Wajub and settles the order as the webhook would, for an order still waiting for its payment.

Orders shipped in several packages

When the products of a cart go with different carriers, PrestaShop splits the order into several orders under one reference. The module treats them as one: one Wajub payment for their total, Pay the rest and Check status from any of them, a refund from any of them paid back from their payments, one list of notes, and an unpaid order cancelled with all the others. The Wajub payment panel of each order, and the customer's line of what is left to pay, say that their amounts are those of all the orders of the reference. A refund made in the Dashboard becomes one credit slip per order, each up to that order's total.

A payment that cannot count yet

A payment that went through, but whose refunds could not be read at that moment, does not count toward its order yet: the order stays as it is, is never cancelled as unpaid for it, and its Wajub payment panel says so. The shop reads the payment again about five minutes later, from the next pages opened on the storefront or in the back office, without waiting for the scheduled task, then again later while it still cannot count. The scheduled task, and opening the order in the back office, read it too. There is nothing to set up.

Refunds

A Partial refund, Standard refund or Return products on the order page is refunded through Wajub before PrestaShop makes its credit slip, for what that slip gives back, tax included, also for a customer whose group sees prices without tax. The payment made last is refunded first.

A refund that Wajub or the module refuses (more than the order's payments hold, an order paid in the other environment or never paid in full) makes no credit slip, with debug mode on or off, and the order page says why. When Wajub refunds a part, then refuses the rest, the part refunded gets a credit slip of its own, and is never refunded twice. A refund given as a voucher gives no money back: nothing goes to Wajub.

The module refunds after the other modules hooked to the refund forms, even one installed after it, so that any of them can refuse the refund first. When another module's error stops PrestaShop once the credit slip is made, the slip still records what Wajub refunded, and a note on the order asks you to check the products' refunded quantities.

A refund made in the Dashboard is recorded on the order as a credit slip. A refund of everything the order was paid moves it to Refunded.

Unpaid orders and the scheduled task

An order left in Awaiting Wajub payment is cancelled after the delay set on the Payment methods tab (60 minutes by default, 0 for never), its products back in stock, unless a payment of it may still go through or Wajub holds money for it. The same task reads again the payments that could not count yet, and sends the expiry e-mails.

PrestaShop's Cron tasks manager module runs it every hour. Without it, have your host's cron call the address on the Payment methods tab every 15 minutes: Copy copies it. It holds a token: keep it private. The tab says when the task last ran, and the back office warns when it has not run for three hours.

Back-office alerts

The module tells the employees who may change its settings what needs their attention, on the pages where it matters, for the shop the shop selector is on. It reads only what is saved: a page of the back office never waits on Wajub.

The alerts link to what fixes them; the scheduled task's says how to run it, and gives its address to copy. Hide for 7 days hides an alert from the employee who clicks it, and it comes back afterwards if what it warns about has not changed.

Multistore

Each shop, group of shops, or All shops can have its own connection: environment, keys and webhook. The back office's shop selector chooses which one the page sets, the page says so, and the Connection tab says where each key comes from. A shop that connected on its own goes back to the shared connection with Use the connection saved for All shops.

Each scope that registers a webhook has its own endpoint, whose address names it (…/module/wajub/webhook?scope=s2), with its own signing secret. An order is settled with the settings of its own shop, whichever address the delivery reached.

Personal data

The module keeps the Wajub payments of each order (ids, amounts, status, method, environment, the customer's id), their refunds and notes, and an order's confirmation e-mail until it is paid. It keeps no name, e-mail address, phone number or card. With PrestaShop's GDPR module, a customer's data export includes their Wajub payments, and erasing a customer deletes the e-mails held and unlinks their payments, which stay as the record of the orders' money.

Uninstall the module

Uninstalling, or Reset in the module manager, deletes the module's settings, keys and signing secrets, and the confirmation e-mails it held. It keeps your orders, their payments, and the record of their Wajub payments, refunds and notes, in three tables: wajub_payment, wajub_refund and wajub_order_note, with your shop's table prefix (ps_wajub_payment by default). PrestaShop's confirmation before uninstalling names them. A new install finds that record again.

To erase that record too, delete the three tables after uninstalling. The orders and their PrestaShop payments stay, but a new install no longer knows which Wajub payments paid them, and cannot refund them through Wajub from the order page.

The keys Connect with Wajub created, and the webhook endpoints, stay in your Wajub account: delete them from the Dashboard, Developers.

Troubleshooting