VibeFox Tap for Adobe Commerce — सहायता

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Store currency: the customer pays in the currency of the cart. It must be 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 store: 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-tap-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/TapPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_TapPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Tap Payments. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, 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). Set Enable to Yes and click Save Config. Test a payment with Tap test cards, then set Test Mode to No.

The module adds the Tap Payments payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Tap payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Tap Payments, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete Settings on Uninstall is read from the Default Config only. Save Config saves the whole page. All fields are in one group; below they are described in the order of the page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (up to 128 characters).); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be non-negative.).

A key with the wrong prefix for its field is not saved: the previous value is kept, the other settings are saved and a warning is shown, for example Tap key was not saved: test_secret_key must start with sk_test_. A live key in a test field is rejected the same way. Spaces around the keys are removed.

Below the license block the page shows the Webhook URL line (see Webhook). While Enable is Yes, it also shows Tap keys of the selected environment are missing. The method is hidden. when the secret key of the current mode is empty (or the publishable key, when the checkout popup is selected), and TEST MODE: no real money is charged. while test mode is on.

General

Enable: shows or hides Tap Payments at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Tap Payments. Required, at most 128 characters.

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

API keys

Find your keys in the Tap dashboard (goSell, API credentials). Test and live keys are separate.

Test Mode: new payments use the test keys, no real money is charged. Default: Yes. Set it to No to take real payments with the live keys. Status checks, webhooks, captures, voids 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. While test mode is on, customers see TEST MODE — no real payment. Do not ship test orders. under the payment method.

Test Publishable Key: starts with pk_test_. Needed only for the checkout popup.

Test Secret Key: starts with sk_test_.

Live Publishable Key: starts with pk_live_. Needed only for the checkout popup.

Live Secret Key: starts with sk_live_.

Merchant ID: optional. Your Tap merchant ID, sent with each payment. Leave it empty unless Tap asked you to route payments to a specific merchant account.

Magento stores the secret keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete a saved secret key, clear the field and click Save Config. The page says the same under the field: Mask keeps a saved secret. Empty deletes it. A wrong prefix keeps the old value with a warning. The publishable keys are public and stay visible. Secret keys are never sent to the browser.

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, for the Tap payment page and the popup.

Webhook

Tap posts the payment result to the URL shown in the Webhook URL line. It is the storefront address of the default store view and looks like https://your-store/wcptappaymentgateway/checkout/notify/. The module sends the webhook address of the store view of the order with every payment, so nothing has to be configured in the Tap dashboard. Just make sure the address 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 changes the order. The webhook works for orders of every store view. Without a working webhook, the order is confirmed only when the customer returns to the store after paying.

Advanced

Debug Logging: logs payment events to var/log/tap_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged; set this to Yes to log every payment event as well. Keys, card numbers and e-mail addresses are not logged. Default: No.

Delete Settings on Uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Tap payment attempts and refunds always stay. Default: No.

Log: at the end of the group, in the Default Config, the page shows the size and the latest entries of the log. Click Clear log to empty it.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Tap Payments for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Tap Payments only for billing addresses in these countries.

Minimum Order Total: offer Tap Payments only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Tap Payments only up to this order total, in the base currency. Leave it empty for no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Checkout

At the payment step the customer chooses the payment method (by default Tap Payments) and sees the description and the note You will be redirected to Tap to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet.

Tap payment page: the module 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. KWD, BHD, OMR and JOD are sent with 3 decimals, SAR, AED, QAR, EGP, EUR, GBP and USD with 2. The customer's e-mail and the name and phone number of the billing address 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.

Tap Checkout popup: the customer goes to a payment page of your store, 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 sees The secure payment window could not be loaded. Use the Tap payment page instead. Reloading the page reuses the same payment attempt.

After paying, the customer returns to your store. 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 belongs to this order and to this payment attempt, and compares the amount and currency with the order. The Tap ID in the return address alone never confirms a payment. The webhook does the same check in the background. Magento then creates the invoice with the Tap charge ID as the transaction ID and sends the order e-mail. The customer sees the standard order success page.

If Tap has not confirmed the payment yet when the customer comes back, the customer sees Your Tap payment is being confirmed or needs review. Do not pay again; contact us if confirmation does not arrive. with the order number and the button Check again. The webhook confirms the order as soon as it arrives. For an authorized payment the page shows Your Tap payment is authorized. Funds are reserved; the merchant must capture them before fulfillment. A customer who comes back in another browser is sent to the cart; the order is still confirmed by the webhook.

If the payment was declined, abandoned or cancelled, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your Tap payment was not completed. Please try again or choose another payment method.

If Tap refuses to start the payment, or the request cannot be sent to Tap at all (for example the secret key of the payment's mode was removed), the order is cancelled, the cart is restored and the customer sees Tap payment could not be started. Check for an existing payment before retrying. in the cart. The reason goes to the log. If the answer of Tap is unclear (for example a timeout), the order stays in Pending Payment and the customer sees the page above; no second payment is started for that order until it is clarified.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the module sends nothing to Tap. A payment that arrives later is not applied to the cancelled order; the order gets a note (see Orders and refunds).

The module works with the standard Magento checkout. It 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. Tap Payments is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Tap, but Tap has not confirmed the payment yet. There is no invoice.

Processing: Tap confirmed a captured payment. The invoice is created with the Tap charge ID (chg_...) as the transaction ID, and a note says that the payment was captured.

On Hold after an authorization: in Authorize only mode the funds are reserved. A note says Tap authorization with its ID confirmed. Capture or void it using the Tap order actions. There is no invoice yet.

On Hold after a mismatch: Tap reported a different amount or currency than the order total, or the order had been put on hold manually. No invoice is created. The note says Amount/currency mismatch. (or Order is manually held.) and asks you to reconcile the payment in the Tap dashboard. Check the payment there, then fulfil the order or refund the payment in the Tap dashboard.

Canceled: the payment was declined, abandoned or could not be started, the authorization was voided, or the order was cancelled in Magento. A payment that arrives after the cancellation is noted with Money/authorization received after cancellation or refund. and is not applied to the order.

Closed: the payment was fully refunded with a credit memo.

If a second successful payment arrives for an order or a cart 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 order but was not started by its payment attempt is only noted. The notes are order comments that the customer does not see.

Tap payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Tap payment, Tap payment ID, Tap authorization, Tap environment (test or live), Tap method and Tap refund status, as far as they are known. The customer sees only the payment method title. The Information tab also shows Tap transaction history: each payment attempt with its reference, Tap ID, environment and status and amount, and the Tap refunds with their ID, amount and status.

Capture and void

In Authorize only mode, open the order. The Information tab shows the buttons Capture Tap payment and Void Tap authorization. Capture Tap payment captures the order total through Tap. Only when Tap confirms the captured charge, Magento creates the invoice and the order goes to Processing. Void Tap authorization releases the reserved funds and cancels the order. The buttons need the Admin rights to capture (Capture) and to cancel orders (Cancel). If Tap rejects the action or does not answer clearly, Magento shows an error, for example Tap capture was not confirmed. Reconcile it before retrying. The standard Magento Invoice capture is not used for Tap payments. 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, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Tap. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Tap.

The refund is made in the order currency, up to the amount Tap actually charged minus the refunds already made. The refund is sent with the secret key of the mode the payment was made in (test or live), so that mode's key must be set. If Tap does not accept the refund, Magento shows the error and the credit memo is not created. An accepted refund is recorded on the order with the Tap refund ID as the transaction ID; its Tap status (for example REFUNDED or PENDING) is shown as Tap refund status. A full refund closes the order. If the answer of Tap is unclear (for example a timeout), further online refunds of that payment are blocked with Earlier Tap refund is unconfirmed. Reconcile before retrying. Check the refund in the Tap dashboard and record it with Refund Offline.

Refunds are available once Tap has confirmed a captured charge and the order has an invoice. A payment on hold after a mismatch, and a payment captured in the Tap dashboard, are refunded in the Tap dashboard. Refunds made in the Tap dashboard do not appear in Magento; create a credit memo with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tap Payments is the first row of the VibeFox Tap Payments group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-tap and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Tap Payments does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has a secret key: Test Secret Key in test mode, Live Secret Key in live mode (and the publishable key of that mode when Checkout Type is the popup). The page shows a warning when a key is missing. Check that the cart currency is one of AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. A maximum of "0.00" counts as a limit in Magento; leave the field empty for no maximum.

The payment went through, but the order stays Pending Payment: the webhook cannot reach your store. Check that the webhook address of your storefront (see Webhook) is reachable from the internet (no firewall or HTTP authentication) and set Debug Logging to Yes to see the answers in the Log field. The order is also confirmed when the customer returns from Tap or clicks Check again.

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 of the website of the order.

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

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

Webhook answers busy: the order was being confirmed by another request at the same moment. Tap retries the webhook.

Webhook answers order not found: the notification names an order that has no Tap payment attempt in this store.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Tap retries the webhook later, and the order is also confirmed when the customer returns.

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 warning names the field.

The customer is back in the cart with Tap payment could not be started: set Debug Logging to Yes and look at the Log field. A wrong key or a rejected request is logged there. The order of that attempt is cancelled.

Order is On Hold after payment: in Authorize only mode capture or void the authorization. Otherwise read the order notes (see Order statuses), then fulfil the order or refund the payment in the Tap dashboard.

Refund fails with Stored-mode Tap secret key missing: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

Refund fails with No refundable native Tap charge: the payment is on hold after a review or was captured in the Tap dashboard. Refund it in the Tap dashboard.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Tap dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Developer events: the Magento events tap_p_charge_payload, tap_p_supported_currencies and tap_p_currency_decimals let a developer change the payment request, the supported currencies and the currency decimals.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_TapPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_TapPayment to remove the data, then bin/magento module:disable Vibefox_TapPayment, delete the folder app/code/Vibefox/TapPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete Settings on Uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Tap payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, 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.