VibeFox Authorize.Net for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

HTTPS: your checkout must use HTTPS. Accept.js refuses to run on plain HTTP pages.

Authorize.Net account: you need the API Login ID, Transaction Key and Public Client Key of your Authorize.Net account, and a Signature Key if you use webhooks. Production (account.authorize.net) and sandbox (sandbox.authorize.net) accounts have different credentials. Authorize.Net accounts are available to merchants in the US, Canada, the UK, Europe, Australia and New Zealand.

Currency: the order currency must be USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD or NZD, and your Authorize.Net account must settle in it. For other currencies the payment method is hidden at checkout.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_authorizenet_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_authorizenet_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_authorizenet_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of the archive into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Authorize.Net Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. Enter the credentials of the sandbox and production accounts (see Configuration). Optionally set up the webhook.

5. Turn on Enable/Disable, choose the Transaction type and click Save. Test a payment in sandbox mode with the card 4111 1111 1111 1111, any future expiry date and any CVV, then turn off Sandbox mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_authorizenet_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Payments. Find VibeFox Authorize.Net Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Webhooks).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Authorize.Net Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the storefront does not use HTTPS (Accept.js works only on HTTPS pages), when the default store currency is not supported by Authorize.Net, when the current mode has no API Login ID, Transaction Key or Public Client Key (the payment method is then hidden at checkout) and when the current mode has no Signature Key (webhooks are then disabled). While sandbox mode is on, it shows Sandbox mode is on: test transactions, no real charges. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must have 1 to 128 characters, Transaction type must be one of the two options, Sort Order must be a whole number, Total must be a number of 0 or more, and the geo zone and order statuses must exist. If any field is wrong, nothing is saved and the page names the field.

Authorize.Net

Enable/Disable: Enable Authorize.Net turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Credit Card. Required, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the card form. Default: Pay securely with your credit card via Authorize.Net.

Sort Order: the position of the card payment among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer the card form only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before the payment method is offered. Leave it empty to offer it for any total.

API credentials

In the Authorize.Net Merchant Interface open Account > Settings > Security Settings. Under API Credentials & Keys copy the API Login ID and create a Transaction Key and a Signature Key. Under Manage Public Client Key copy the Public Client Key. Sandbox and production use different credentials. The section shows the fields of both modes, so you can keep both sets.

Sandbox mode: uses the Authorize.Net sandbox (test transactions, no real charges). It switches the API endpoint, Accept.js and the set of credentials used for new payments. Default: on. Turn it off to take real payments. While it is on, customers see Sandbox mode: with the test card 4111 1111 1111 1111 above the card form.

Sandbox API Login ID and Live API Login ID: the API Login ID of the sandbox or production account.

Sandbox Transaction Key and Live Transaction Key: the Transaction Key of that account.

Sandbox Public Client Key and Live Public Client Key: the public key used by Accept.js in the browser.

Sandbox Signature Key and Live Signature Key: needed only for webhooks. It verifies the X-ANET-Signature header of each notification.

Saved Transaction Keys and Signature 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. To remove a saved key, tick Clear the saved value on save under the field and click Save.

Payment

Transaction type: how the card is charged. An authorization expires after 30 days.

Webhooks (recommended)

Without webhooks, orders held by the Fraud Detection Suite or captured or voided in the Authorize.Net panel must be updated by hand. In the Merchant Interface go to Account > Settings > Business Settings > Webhooks and click Add Endpoint, in the sandbox and in the production account. Use the URL shown in Endpoint URL in this section. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_authorizenet_gateway/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_authorizenet_gateway/payment/wcp_authorizenet_gateway.webhook. It is built from the storefront address of your OpenCart installation. Copy the URL exactly as the settings show it. Select these events (they are also listed in this section):

Enter the Signature Key of each account in Sandbox Signature Key or Live Signature Key. Webhooks without a valid signature are rejected. A notification must be signed with the key of the mode the payment was made in; a notification of the other mode changes nothing. For each notification the extension also asks Authorize.Net for the current status and amount of the transaction before the order changes, so repeated notifications change nothing. The webhook also works while the store is in maintenance mode, because OpenCart lets payment extension requests through.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). It gets a status only after Authorize.Net has answered for the card. Each field below lists your OpenCart order statuses.

Order Status After Payment: the card was charged (Authorize and capture, or a capture later). Default: Processing.

Authorized Status: Authorize only: the funds are reserved, not captured yet. Capture payment on the order tab is offered only in this status. Default: Pending.

On Hold (Review) Status: held for review by the Fraud Detection Suite, or the charged or captured amount differs from the order. A note explains why. Default: Pending, because OpenCart has no On hold status. You can create your own statuses in System > Localisation > Order Statuses and select them here.

Canceled Status: declined, voided or expired in Authorize.Net without a payment (webhook), or the authorization was voided from the order tab. Default: Canceled.

Refunded Status: set after the payment is fully refunded (or a paid transaction is voided) from the order tab. Default: Refunded.

Advanced

Debug log: writes API requests and responses to wc_ang_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to wc_ang_debug.old.log.php. Keys, card tokens and personal data are masked. Default: off. Errors, such as declined or failed payments, API errors and failed refunds, are always logged, even when this is 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 extension removes the settings and the log. The Authorize.Net transactions and refunds always stay, so orders paid before can still be captured and refunded after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Transaction Keys and Signature Keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved secret keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit Card). At the Confirm Order step the customer sees your description and enters the card number, expiry date (MM/YY) and card code (CVV) in the form above the confirm button. OpenCart creates the order at this step, still without a status. Accept.js is loaded from Authorize.Net only with this form. When the customer clicks Confirm Order, Accept.js exchanges the card data for a one-time token in the browser. The card fields have no form names, so the card number and CVV are never sent to your server.

The extension charges the token through the Authorize.Net API for the order total in the order currency. The billing address, e-mail and IP address are sent with the transaction for address verification and fraud filters, and the order number is sent as the invoice number. The order is marked paid only after Authorize.Net confirms it: if the transaction is approved, the order gets its status the standard OpenCart way, with the usual order e-mails and stock update, the cart is emptied and the customer sees the OpenCart order success page with Your card payment has been received. With Authorize only the page shows Your card payment has been authorized. The amount will be charged when your order is processed. If the Fraud Detection Suite holds the transaction, it shows Your payment is being reviewed. We will update your order as soon as the review is complete.

If the card is declined, the customer stays at the Confirm Order step and sees Payment failed: followed by the reason under the form, for example a declined card, a wrong card code or an expired card. The order stays without a status, the cart is kept, and the customer can enter another card. Configuration and API errors are not shown to customers: they see a general message, and the details go to the log. If the store cannot reach Authorize.Net, the customer sees Payment error: unable to connect to the payment gateway. Please try again. If the card fields are empty, the form asks Please enter the card number, expiry date and card code.

A double click, a second tab or a repeated submit never charges an order twice. OpenCart 3 creates a new order each time the Confirm Order step is shown, so one cart can have several orders (on OpenCart 4 an earlier order or a second browser tab can still hold the same cart): once one of them is paid, another order of the same cart is not charged. The customer sees This cart has already been paid with order #…. Please check your order history — do not pay again. A second attempt while the first one is still running shows Your payment is already being processed. Please wait a moment and check your order history before trying again. If a payment was approved but the order status could not be set, the customer sees Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. The order then gets its status from the approved payment on the next attempt or by the webhook, without charging the card again.

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options. The card form then appears in the order confirmation block at the bottom of the checkout page, above Confirm Order. The payment address is optional on OpenCart 4: without it, the shipping address is sent to Authorize.Net as the billing address. OpenCart 4 keeps one order for the checkout and updates it, so after a declined card the customer pays the same order. If that order was closed meanwhile (for example you cancelled it), or it is already paid and the cart now holds a new purchase, Confirm Order takes the customer back to the checkout page, and the next Confirm Order pays a new order. Above the checkout page the customer sees Your previous order is closed (cancelled or refunded by the store). Please confirm the order again: the cart will be paid with a new order. when the order was closed, or Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. when it was paid for an earlier cart. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

If the amount charged does not match the order total, the order goes to On Hold (Review) Status with a note, and the payment is recorded for the amount actually charged.

The extension has no saved cards or customer profiles, no subscriptions or recurring payments, no eCheck/ACH, Apple Pay, Google Pay, PayPal or 3-D Secure, no partial capture of an authorization and no automatic currency conversion.

Orders and refunds

Order statuses

No status (missing order): the card was declined or the payment failed. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): the card was charged (Authorize and capture), or an authorization was captured. A note shows the amount, Trans ID, auth code, card type and last four digits.

Authorized Status (default Pending): the funds are only authorized (Authorize only). Capture them before fulfilment.

On Hold (Review) Status (default Pending): the Fraud Detection Suite held the transaction for review, the amount charged does not match the order total, or a capture reported by webhook does not match the order amount. The note explains it. Approve or decline a held transaction in the Authorize.Net panel; with webhooks the order is updated automatically.

Canceled Status (default Canceled): a webhook reported that the transaction was declined, voided or expired before the order was paid, or you voided an authorization that was not captured. If a paid order's transaction is voided in the Authorize.Net panel, its status is not changed and a warning note is added.

Refunded Status (default Refunded): the payment was fully refunded or voided through the extension.

On OpenCart 4 an unpaid order of the checkout can get the status Voided, which OpenCart 4 sets when the customer comes back to the Confirm Order step. The extension treats such an order as an order without status: a later payment or webhook still sets its status.

Notes are entries in the order History that the customer does not see.

VibeFox Authorize.Net Gateway tab

In Sales > Orders open an order paid with Authorize.Net. At the bottom of the order page, next to History and Additional, the VibeFox Authorize.Net Gateway tab shows the Trans ID with a Sandbox label for sandbox payments, the Transaction type, the transaction Status, the Card and auth code, the amounts Charged / order / refunded, the capture button, the refund form, the refund history and the Authorize.Net notes of the order. The tab is shown to users who have access to the extension. Capture and refunds need the right to modify the extension (set in System > Users > User Groups).

Capture

For an order in Authorized Status, click Capture payment in the tab and confirm Capture the authorized amount through Authorize.Net? The authorized amount is captured and the order gets the Order Status After Payment. If the capture fails, the error is shown and added to the notes. You can also capture in the Authorize.Net panel; with webhooks the order is updated automatically.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), click Refund via Authorize.Net and confirm Refund this amount through Authorize.Net? This cannot be undone. A refund of the full amount first voids the transaction if it is not settled yet, or an authorization that was not captured. Settled transactions, usually after 24 hours, can be refunded fully or partially. Before settlement a partial refund is not possible: refund the full amount to void the transaction, or try again after settlement. Refunds are made in the amount and currency Authorize.Net charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. If Authorize.Net does not accept the refund, the tab shows the error and no refund is recorded. A successful refund or void is added to the refund history and the notes. A full refund sets the order to Refunded Status (Canceled Status when only an authorization was voided) without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. While a transaction is held for review, refunds are not offered.

Captures, refunds and webhook checks of an order use the credentials of the mode the order was paid in, so orders of the other mode can still be captured and refunded after you switch Sandbox mode. Keep the credentials of that mode in their fields until those orders are done.

Product returns in Sales > Returns do not send money back through Authorize.Net. Refunds made in the Authorize.Net panel are not reported to the store: update the order manually.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Authorize.Net Gateway is the first block on Extensions > Extensions > Payments > VibeFox Authorize.Net Gateway > Edit, 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: opencart-payment-authorizenet and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the Authorize.Net card payment 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and captures and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

The card payment does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has an API Login ID, Transaction Key and Public Client Key. The settings page shows a warning when one is missing. Check that the customer's currency is supported, that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays in the authorized or review status: the transaction type is Authorize only (capture it in the order tab), or Authorize.Net held the transaction for review. Approve or decline it in the Authorize.Net panel. To have such orders updated automatically, set up the webhook: check that the endpoint exists in the account of the mode you use, that its URL is exactly the one shown in Endpoint URL, that the four events are selected and that the Signature Key of that account is entered.

Webhook answers webhooks are not configured: no Signature Key is entered for either mode.

Webhook answers invalid signature: the Signature Key belongs to another account, or a key was changed in Authorize.Net. Create or copy the Signature Key again and paste it into the field of its mode.

Webhook answers mode mismatch: the notification was signed with the key of one mode, but the payment was made in the other mode. Check that the sandbox and live Signature Keys are not swapped.

Webhook answers verification failed, retry later: the store could not read the transaction from the Authorize.Net API, or the credentials of the payment's mode are missing. Authorize.Net retries the delivery.

Webhook answers busy, retry later: the order was being updated by another request at the same moment, or processing failed. Authorize.Net retries the delivery. Look at the Log field for the reason.

The webhook URL shows method not allowed in the browser: this is normal. The URL accepts only requests from Authorize.Net.

The card form shows The secure card form (Accept.js) could not be loaded: the checkout must use HTTPS, and the Public Client Key and API Login ID of the current mode must be correct.

Payment error: the card could not be tokenized: Accept.js did not return a token. The customer should re-enter the card details and try again.

The customer sees This payment method is not available: the checkout session no longer matches the order, the payment method was turned off meanwhile, the credentials are missing or the order total is zero. With Please reload the checkout page the customer reloads the checkout.

The customer sees a general error: look at the Log field on the extension page; errors are always written there. A currency the account does not support is rejected by Authorize.Net.

A partial refund fails because the transaction is not settled yet: refund the full amount to void the transaction, or retry after settlement, usually within 24 hours.

Refund or capture fails with a message about the mode: the payment was made in sandbox or live mode, and the API Login ID and Transaction Key of that mode are not set. Enter them and try again.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Authorize.Net Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events, including the one that shows the message above the checkout page, and its startup action, which lets the webhook through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, sandbox mode, credentials, transaction type, logging) and the log are removed. If it is off, they are kept for a later re-install. The Authorize.Net transactions and refunds are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Authorize.Net Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Authorize.Net is a trademark of its respective owner. This extension is not affiliated with or endorsed by Authorize.Net.