VibeFox Tap for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Shop currency: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR or USD. For carts in other currencies the payment method is hidden at checkout.

Internet access to your shop: Tap sends the payment result to a webhook on your shop, so the site must be reachable from the internet. The webhook URL is sent with every payment; nothing has to be configured in the Tap dashboard.

Tap account: you need the API keys from your Tap dashboard (goSell, API credentials). Test keys start with pk_test_ / sk_test_, live keys with pk_live_ / sk_live_. The secret key is always needed; the publishable key only for the checkout popup. Which payment methods are offered (mada, KNET, Benefit and others) and Apple Pay domain verification are set up in your Tap account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Tap Payments in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter your Tap test and live keys, choose the payment action, the checkout type and the Tap page language (see Configuration).

5. Turn on Enable / Disable and click Save. Test with Tap test cards, then turn off Test mode.

On install the module creates two order statuses, Tap payment authorized and Tap payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Tap Payments > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows Test mode is on: payments use your Tap test keys and no real money is charged. or Live mode: real payments are accepted. It also warns you when the keys of the current mode are missing (the payment method is then not shown at checkout) and when the default shop currency is not offered with Tap.

When you save, a key with the wrong prefix for its field is not saved: the previous value is kept, the other settings are saved and a message such as Test secret key was not saved: a Tap key for this field starts with "sk_test_". is shown. For example, a live key in a test field is rejected. An empty Title is not accepted: the page shows Enter a title for the payment method. and nothing is saved.

Tap Payments

The section title also shows TEST or LIVE for the current mode.

Enable / Disable: Enable Tap Payments turns the payment method on or off. Default: off.

Title: the payment method name shown at checkout. It is also the payment method name stored in the order. Default: Tap Payments. Required.

Description: the text shown under the payment method at checkout. Default: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Tap API keys

Find your keys in the Tap dashboard (goSell, API credentials). Test keys start with pk_test_ / sk_test_, live keys with pk_live_ / sk_live_.

Test mode: uses the test keys, no real money is charged. Payments, status checks, captures and refunds always use the keys of the mode the payment was made in, so a test payment is still checked and refunded with the test key after you switch to live. Default: on. While it is on, customers see Test mode: no real payment will be made. under the payment method.

Test publishable key: starts with pk_test_. Needed for the popup.

Test secret key: starts with sk_test_.

Live publishable key: starts with pk_live_. Needed for the popup.

Live secret key: starts with sk_live_.

Merchant ID: optional. Your Tap merchant ID, only needed if Tap asked you to route payments to a specific merchant account.

Saved secret keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. The publishable keys are public and stay visible.

Clear saved secrets: tick a secret key and click Save to remove it. An empty field keeps the saved value.

Payment

Payment action: what happens to the money when the customer pays.

Checkout type: where the customer pays.

Tap page language: English (default) or Arabic.

Payment notifications (webhook)

Tap posts the payment result to the URL shown in Webhook URL in this section. With friendly URLs it looks like https://your-shop/module/wcp_tap_payment_gateway/webhook, possibly with a language code such as /en/. The URL is sent with every payment, so nothing has to be configured in the Tap dashboard. Just make sure it is reachable from the internet (not blocked by a firewall or HTTP authentication). Each notification is checked with the hashstring signature (HMAC-SHA256 with the secret key of the mode the payment was made in). Webhooks without a valid signature are rejected. Even a signed notification is not trusted as such: the module reads the payment again from the Tap API before it creates or changes the order. Without a working webhook, the order is created only when the customer returns to the shop after paying.

Advanced

Debug log: logs payment events to logs/tap_p_debug.log.php in the module folder. The file cannot be read from the web. Errors and warnings are always logged; turn this on to log every payment event as well. The log never contains keys, card or customer data. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the gateway settings and the log. Order payment records are kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Tap Payments) and confirms the order. No order exists yet at this point.

Tap payment page: the module creates a Tap charge (or an authorization in Authorize only mode) for the cart total in the cart currency, with the description Cart # and the cart number, and sends the customer to the Tap payment page. The customer's name, e-mail and phone number are passed to Tap. There the customer chooses a card, mada, KNET, Benefit, Apple Pay or Google Pay (as enabled in your Tap account) and pays. If Tap cannot start the payment, the customer stays at checkout with The Tap payment could not be started. Please try again or choose another payment method. and the reason goes to the log.

Tap checkout popup: the customer goes to the Tap payment page of the module, where the Tap payment form opens. The page also shows the link Pay on the Tap payment page instead. If the window is closed, the button Pay now opens it again. If the form cannot be loaded, the customer is asked to use the Tap payment page. Reloading the page reuses the same payment attempt.

After paying, the customer returns to your shop. The order is marked paid only after Tap confirms it: the module reads the payment from the Tap API with the key of the payment's mode, checks that it refers to this cart and was started by its checkout, and compares the amount and currency with the cart. The Tap ID in the return address alone never creates an order. The webhook does the same check in the background. The order is then created and the customer sees the standard order confirmation page. For an authorized payment the page shows Your payment has been authorized. We will process the order as soon as the payment is captured. For an order on hold it shows Your payment is being reviewed. We will contact you if anything else is needed.

If Tap has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. with the buttons Check again and Back to checkout. The webhook creates the order as soon as it arrives.

If the payment was declined, abandoned or cancelled, no order is created. The customer is back at checkout with Your payment was not completed. Please try again or choose another payment method. (with the reason from Tap when Tap gives one). An unfinished payment shows The payment was not completed. You can try again or choose another payment method. The cart is kept and can be paid again.

Other messages at checkout: Tap does not accept payments in followed by the currency, when the cart currency is not supported, and The order total must be greater than zero to pay with Tap.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module has no saved cards or tokenization, no subscriptions and no card fields embedded in your checkout page. Capture Tap payment always captures the order total; partial capture is not supported.

Orders and refunds

Order statuses

No order yet: the customer was sent to Tap and has not paid, or Tap has not confirmed the payment yet. Only the cart exists.

Payment accepted: Tap confirmed a captured payment. The payment is recorded with the Tap charge ID (chg_...) as the transaction ID, and a note shows the amount, the charge ID, the payment method and (test mode) for test payments.

Tap payment authorized: the payment was authorized only and waits for capture or void.

Tap payment on hold: the paid amount or currency differed from the cart (Tap: amount/currency mismatch — manual review required.), or a payment arrived after the order had been cancelled. The note explains it. Check the order and fulfil it, or refund the payment.

Canceled: the authorization was voided with Void Tap authorization, so the reserved funds were released.

Refunded: the payment was fully refunded through the module.

A failed attempt never changes a paid, authorized or cancelled order. If a second successful payment arrives for an order that is already paid, the order is not changed. A note says it is a duplicate payment and asks you to refund it in the Tap dashboard. A payment that refers to the cart but was not started by its checkout is only noted.

Tap payment block

The order page shows a Tap payment block with the Tap ID, the authorization and the charge, the mode (a Test mode badge for test payments), the payment status and method, Charged / refunded, the refund history, the payment attempts of the cart and the Payment notes of the order. The buttons of the block work on the order page itself; you need the right to edit orders, not access to the module settings.

Capture and void

In Authorize only mode, open the order in Tap payment authorized. Capture Tap payment (with the order total on the button) captures the order total after the question Capture the reserved funds of this order through Tap?; the order then becomes Payment accepted. Void Tap authorization asks Release the reserved funds? The order will be canceled., releases the funds and sets the order to Canceled. If Tap rejects the action, an error is shown in the block and added to the notes. If an authorization is captured directly in the Tap dashboard, the webhook marks the order paid; refunds for such a payment must be made in the Tap dashboard.

Refunds

In the Tap payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Tap. Confirm the question Refund this amount through Tap? This cannot be undone. Full and partial refunds are supported for captured Tap charges. You can refund up to the amount and currency Tap actually charged, even if the order was edited later. The refund is sent with the secret key of the mode the payment was made in, so that mode's key must be set. A refund accepted by Tap is added to the refund history and the notes with the Tap refund ID and status. If Tap rejects it, the block shows the error and no refund is recorded. A full refund sets the order to Refunded; a partial refund does not change the status. For an authorized order refunds are available once the authorization is captured. An order on hold after an amount or currency mismatch is refunded in the Tap dashboard.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Tap. Refunds made in the Tap dashboard do not appear in PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tap Payments is the first block on Modules > Module Manager > VibeFox Tap Payments > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-tap and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Tap Payments is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds, capture and void work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Tap Payments does not appear at checkout: check that the license is active, Enable / Disable is on and the current mode has a secret key (and a publishable key when Checkout type is the popup). Check that the cart currency is one of AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows a warning for missing keys and an unsupported shop currency.

The payment went through, but no order was created: the webhook cannot reach your shop. Check that the URL shown in Webhook URL is reachable from the internet (no firewall or HTTP authentication) and turn on Debug log to see the answers in the Log field. The order is also created when the customer returns from Tap.

Webhook answers invalid signature: the notification was not signed with the secret key of the payment's mode. Check the secret keys in the settings.

Webhook answers gateway not configured: the secret key of the payment's mode (test or live) is empty. Enter it.

Webhook answers verification failed: the Tap API could not be reached to check the payment. Tap retries the webhook later.

Webhook answers order not found: the notification names a cart that has no Tap payment attempt in this shop.

Webhook answers busy, retry later or order could not be updated, retry later: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Tap retries the webhook. Look at the Log field for the reason.

A key is not saved: the key must start with the prefix of its field: pk_test_, sk_test_, pk_live_ or sk_live_.

The customer sees The Tap payment could not be started: look at the Log field on the module page. A wrong key or a rejected request is logged there.

The customer sees We could not match this payment to an order: the payment does not belong to this cart or was not started by its checkout. If money was taken, check the payment in the Tap dashboard.

The order is Tap payment on hold: read the notes in the Tap payment block. The paid amount or currency did not match the cart, or the payment arrived after the order had been cancelled.

Refund fails with a message about the mode: the payment was made in test or live mode, and no secret key is configured for that mode. Enter it and try again. If the block says no captured Tap charge was found, refund the payment in the Tap dashboard.

Developer hooks: the hooks actionWcpTapChargePayload, actionWcpTapSupportedCurrencies and actionWcpTapCurrencyDecimals let a developer change the payment request, the supported currencies and the currency decimals.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Tap Payments and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Tap payment attempts and refunds and the order statuses Tap payment authorized and Tap payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

Tap Payments is a trademark of its respective owner. This module is not affiliated with or endorsed by Tap Payments.