VibeFox Tap for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

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

Internet access to your site: Tap sends the payment result to a webhook on your store, 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_tap_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Tap Payments > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

6. Turn on Enable / Disable and save. Test with Tap test cards, then untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Tap Payments. Above the fields the page shows Test mode is on: payments use your Tap test keys and no real money is charged. while test mode is on. It also tells you when the keys of the current mode are missing (the gateway is then not shown at checkout) and when the store currency is not offered with Tap. In the list of payment methods, Tap Payments is marked as needing setup until the current mode has a secret key (and, for the popup, a publishable key).

When you save, a key with the wrong prefix for its field is not saved: an error is shown and the previous value is kept. For example, a live key in a test field is rejected.

General

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

Title: the payment method name shown at checkout. Default: Tap Payments.

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: Use the test keys (no real money is charged). Payments, status checks 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.

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.

Payment

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

Charge (capture immediately): the payment is captured at once (default).

Authorize only (capture later from the order): the funds are only reserved. Authorized orders are put on hold; capture them with the order action Capture Tap payment or release the funds with Void Tap authorization.

Checkout type: where the customer pays.

Tap payment page (redirect, recommended): the customer pays on the secure Tap hosted page (default).

Tap checkout popup on your site: the Tap Checkout SDK opens on the order payment page. The Tap payment page stays available as a fallback. Needs the publishable key of the current mode.

Tap page language: English (default) or Arabic.

Payment notifications (webhook)

Tap posts the payment result to the URL shown in this section. It looks like https://your-site/wc-api/tap_p_webhook/. 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, maintenance mode or HTTP authentication). Each notification is checked with the hashstring signature (HMAC-SHA256 with the secret key of the payment's mode). Webhooks without a valid signature are rejected. Even a signed notification is not trusted as such: the plugin reads the payment again from the Tap API before it changes the order. Without a working webhook, the order is updated only when the customer returns to the store after paying.

Advanced

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Errors are always logged. The log never contains keys, card or customer data. Default: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). Default: off.

Checkout

The customer chooses the payment method (by default Tap Payments) and places the order. In test mode the checkout shows Test mode: no real payment will be made.

Tap payment page: the plugin creates a Tap charge (or an authorization in Authorize only mode) for the order total in the order currency, with the description Order # and the order number, and sends the customer to the Tap payment page. 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 sees The Tap payment could not be started. Please try again or choose another payment method. and the reason goes to the order notes.

Tap checkout popup: the customer goes to the order payment page, 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.

After paying, the customer returns to the order received page. The order is marked paid only after Tap confirms it: the plugin reads the payment from the Tap API with the key of the payment's mode, checks that it refers to this order and was started by its checkout, and compares the amount and currency with the order. The Tap ID in the return address alone never marks an order as paid. The webhook does the same check in the background. Repeated webhooks and returns never change the order twice (one change at a time per order).

If the payment is not confirmed yet, the order received 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. For an authorized payment it shows Your payment has been authorized. We will process the order as soon as the payment is captured.

If the payment was declined or abandoned, the order is marked Failed and the customer goes back to the Pay for order page with the message 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 below. The customer can pay the order again from that page.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

Pending payment: the customer was sent to Tap and has not paid yet, or Tap has not confirmed the payment yet.

Processing: Tap confirmed a captured payment. This is the standard WooCommerce status after payment (orders with only virtual downloadable products become Completed). The order note shows the amount, the Tap charge ID (chg_...), the payment method and (test mode) for test payments. The transaction ID is the Tap charge ID.

On hold: the payment was authorized only and waits for capture; or the paid amount or currency differed from the order (Tap: amount/currency mismatch — manual review required.); or a payment arrived after the order had been cancelled. The order note explains it.

Failed: the payment was declined, abandoned, cancelled or timed out. Only an order that still waits for payment is marked Failed; a failed attempt never changes a paid, authorized or cancelled order. The customer can pay again.

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

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

Capture and void

In Authorize only mode, open the on-hold order and choose in Order actions: Capture Tap payment captures the order total; the order then becomes paid. Void Tap authorization releases the funds and cancels the order. If Tap rejects the action, an error is shown and added to the order 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

Open the order, click Refund, enter the amount and click Refund via Tap Payments (the button shows your Title). Full and partial refunds are supported for captured Tap charges. 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 order notes with the Tap refund ID and status. If Tap rejects it, WooCommerce shows the error and no refund is recorded. Refunds made in the Tap dashboard do not appear in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Tap Payments. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds, capture and void work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency (or the order currency on the Pay for order page) is one of AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. The settings page shows a notice for each of these problems.

The payment went through, but the order stays Pending payment: the webhook cannot reach your site. Check that the URL shown in the settings (/wc-api/tap_p_webhook/) is reachable from the internet (no firewall, maintenance mode or HTTP authentication) and look at WooCommerce > Status > Logs, source wcp_tap_payment_gateway. The order is also updated 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.

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 order is On hold: read the order note. The payment was authorized only (capture it from the order actions), the paid amount or currency did not match the order, 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 note says no captured Tap charge was found, refund the payment in the Tap dashboard.

Developer hooks: the filters tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url and tap_p_payment_page_hosts are available.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the plugin's other options and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, Tap IDs and transaction IDs.

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