VibeFox CorvusPay 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.

Currency: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK or USD. In any other checkout currency the payment method is hidden at checkout. Amounts are sent with 2 decimals; a total with more decimals (for example in a currency with 3 decimals such as BHD) is refused instead of being rounded.

CorvusPay account: you need a CorvusPay merchant account. CorvusPay issues a Store ID and a Secret Key for each store, separately for the test and the production store; they are shown in the CorvusPay Merchant Center. The Success URL and Cancel URL of the extension must be entered there (see Configuration).

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_corvuspay_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_corvuspay_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_corvuspay_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 this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox CorvusPay 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 Store ID and Secret Key of your CorvusPay test store (and of the production store for live payments). Copy the Success URL and Cancel URL shown on the settings page into the CorvusPay Merchant Center, for the test and the production store.

5. Turn on Enable/Disable and click Save. Place a test order, then turn off Test Mode to go live.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_corvuspay_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 type Payments. Find VibeFox CorvusPay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the CorvusPay stores and the Merchant Center URLs as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the Success URL and Cancel URL are different (see Success and Cancel URLs).

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

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page shows Test mode is on. Payments go to the CorvusPay test environment — no real money is taken. while test mode is on, warns you when the gateway is enabled but the Store ID or Secret Key of the current mode is empty (it is then hidden at checkout until they are filled in) and when the default currency of your store is not supported by CorvusPay. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be longer than 128 characters, Sort Order must be a whole number, Minimum Total a number that is not negative, and the selected geo zone and order statuses must exist; otherwise nothing is saved and the page lists the errors.

CorvusPay

Enable/Disable: Enable CorvusPay Gateway. 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/Debit Card (CorvusPay). Up to 128 characters; if you leave it empty, the default name is shown.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely with your credit or debit card via CorvusPay. In test mode (Test mode — no real payment is taken.) is added to it.

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

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

Minimum Total: the order total, in the default currency of the store, that an order must reach before CorvusPay is offered. Leave it empty for no minimum.

Store credentials

The Store ID and Secret Key are issued by CorvusPay for each store (test and production separately) and are shown in the CorvusPay Merchant Center.

Test Mode: uses the CorvusPay test environment (wallet.test.corvuspay.com) and the test Store ID and Secret Key. Default: on. Turn it off to take real payments on wallet.corvuspay.com.

Test Store ID: the numeric Store ID of your CorvusPay test store.

Test Secret Key: the Secret Key of your CorvusPay test store, used for the HMAC-SHA256 signatures.

Live Store ID: the numeric Store ID of your CorvusPay production store.

Live Secret Key: the Secret Key of your CorvusPay production store, used for the HMAC-SHA256 signatures.

A Store ID must contain digits only. If you enter anything else, the page shows … must contain digits only — the previous value was kept. and the other fields are still saved. 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. To remove a saved key, tick Clear the saved value on save under the field and click Save. A payment is always verified with the Secret Key of the store it was started in, so keep the test key filled in while test payments may still return.

Success and Cancel URLs

Copy the two addresses shown in Merchant Center URLs into the CorvusPay Merchant Center, for the test and the production store. CorvusPay returns the customer to them after the payment. They are built from the storefront address of your OpenCart installation; copy them exactly as the page shows them.

Payment

Transaction Type: how the card is charged.

Payment Page Language: the language of the CorvusPay payment page. Site language (default) uses the current language of your store when CorvusPay supports it, otherwise English. You can also choose Hrvatski, English, Deutsch, Italiano, Srpski or Slovenščina.

Order Status After Payment: the order status after a successful Sale payment. The options point to the OpenCart statuses chosen in the Order statuses section.

Order statuses

OpenCart creates the order at the Confirm Order step without a status (a missing order). These are the OpenCart statuses the gateway sets; each field lists your OpenCart order statuses. OpenCart has no On hold status, so the review status is used for Authorize only, amount or currency mismatches and payments after a cancellation; an order note explains why.

Processing status: used when Order Status After Payment is Processing. Default: Processing.

Completed status: used when Order Status After Payment is Completed. Default: Complete.

On hold (review) status: Authorize only, amount or currency mismatch, payment after a cancellation, or Order Status After Payment set to On hold. Default: Pending. You can create your own status in System > Localisation > Order Statuses and select it here.

Advanced

Logging: writes debug information to corvuspay_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Errors are always logged, even when this is off; secrets, signatures and customer data never are. Default: off.

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

Delete Data: when on, uninstalling the extension removes the gateway settings and the log files. Orders and the CorvusPay transaction data are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Secret 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/Debit Card (CorvusPay)). At the Confirm Order step the customer sees your description; OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the page shows Redirecting to CorvusPay for payment. Please wait... and sends the signed form to the CorvusPay payment page. If the redirect does not start, the customer clicks Pay via CorvusPay. The order total in the order currency, a short description (Order, the order number and the store name) and the customer's address details and e-mail (to pre-fill the payment page) are sent. The same CorvusPay order number is reused while the amount, currency, mode and transaction type do not change, and CorvusPay does not accept a second payment for it. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. If the store does not ask for a payment address (the OpenCart 4 default), the card holder details are taken from the customer's name and the delivery address.

After paying, CorvusPay returns the customer to the Success URL. The order is marked paid only after CorvusPay confirms it: the CorvusPay order number must have been issued by this store, the signature must match the Secret Key of the store the payment was started in, and the amount and currency must match the order. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page with Your CorvusPay payment has been received. For Authorize only the page shows Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order. and for an order in the review status Your payment was received and is being reviewed by the shop.

If the payment cannot be applied at that moment (for example, another request is confirming the same order), the customer sees Your payment is being confirmed with a Check again button, which leads to the success page as soon as the order has its status. If the Success URL request cannot be verified, the customer sees Payment not confirmed and We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Nothing is changed. The Success URL also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action for the Success and Cancel URLs. On OpenCart 4 the browser does not send the store session when CorvusPay sends the customer back, so the extension first shows a short page that opens the same address again from your store: the customer keeps the cart and the login.

If the customer cancels on the CorvusPay page, the order stays without a status and the customer returns to the checkout with the cart intact and The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. On OpenCart 4 this message is shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, and a new attempt gets a new CorvusPay order number. If another order of the same cart is already paid, the customer is sent to the success page instead of paying again.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example you cancelled it), Confirm Order or the return from CorvusPay sends the customer back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. If the order already has a status and the cart has changed since (other products or quantities), the message is Your previous order is already placed. The cart has changed since then: please confirm the new order to pay for it. In both cases the next Confirm Order pays a new order of the cart.

If the payment cannot start, the customer stays at the Confirm Order step with a short message above the button: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … or This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

The order is confirmed only when CorvusPay returns the customer to the Success URL; there are no server-to-server notifications. If the customer closes the browser right after paying, the order stays without a status. The extension has no refunds, captures or voids from OpenCart (the CorvusPay server API requires a client certificate), no saved cards, subscriptions, installments or on-site card form.

Orders

Order statuses

No status (missing order): the customer was sent to CorvusPay and has not returned with a confirmed payment, or cancelled the payment. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. If the customer paid but did not return, check the payment in the CorvusPay Merchant Center and set the order status manually.

Processing, Completed or review status: the Sale payment was confirmed. The status follows Order Status After Payment. A note shows the CorvusPay order number, the approval code and the card type.

Review status, authorized: Authorize only is selected. Capture the payment in the CorvusPay Merchant Center, then change the order status.

Review status, amount or currency mismatch: the paid amount or currency does not match the order. Do not ship before verifying the payment in the CorvusPay Merchant Center.

Review status, payment after cancel: a successful payment arrived for a payment attempt the customer had cancelled. Fulfil the order or refund the payment in the CorvusPay Merchant Center.

If another successful payment arrives for an order that is already paid, the order is not changed. A note asks you to check the CorvusPay Merchant Center and refund the duplicate payment if needed. If a payment arrives for another order of the same cart while one order is already paid, that order stays without a status and the note is added to the paid order.

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

VibeFox CorvusPay Gateway tab

In Sales > Orders open an order paid with CorvusPay. At the bottom of the order page, next to History and Additional, the VibeFox CorvusPay Gateway tab shows the CorvusPay order number, the Status of the payment attempt, the Transaction type, the Amount (and the amount received, if CorvusPay reported it), the Approval code, the Transaction, the Card type and the CorvusPay notes. Test payments are marked Test. The tab is read-only and is shown to users who have access to the extension.

Refunds: refunds, captures and voids from OpenCart are not supported. Do them in the CorvusPay Merchant Center and record the result in OpenCart manually. Product returns in Sales > Returns do not send money back through CorvusPay.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox CorvusPay Gateway is the first block on Extensions > Extensions > Payments > VibeFox CorvusPay 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-corvuspay 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, CorvusPay 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 when the customer returns from CorvusPay.

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

CorvusPay does not appear at checkout: check that the license is active, Enable/Disable is on, the Store ID and Secret Key of the current mode are filled in (Test Store ID and Test Secret Key in test mode, Live Store ID and Live Secret Key in live mode) and the checkout currency is supported by CorvusPay. Also check that the payment address is in the selected Geo Zone and that the order reaches the Minimum Total.

The payment went through, but the order stays without a status: the Success URL is probably not entered in the CorvusPay Merchant Center, or the Secret Key in OpenCart does not match the store. Look for INVALID signature in the Log field on the extension page (errors are always logged). The order also stays without a status if the customer closed the browser before returning; then check the payment in the Merchant Center and set the order status manually.

The customer sees Payment not confirmed: the Success URL request was rejected: required fields were missing, the CorvusPay order number was not issued by this store, the Secret Key of that store is empty or the signature did not match. Nothing is changed. The log shows the reason.

The customer sees Your payment is being confirmed for a long time: the order status could not be set. The log shows the reason; check the payment in the Merchant Center.

The customer sees This order total cannot be paid via CorvusPay: the total is zero or has more than 2 decimals.

The customer sees CorvusPay is not configured or CorvusPay does not accept payments in …: the Store ID or Secret Key of the current mode is missing, or the checkout currency is not supported.

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

Order is in the review status: read the notes in the VibeFox CorvusPay Gateway tab. Authorize only is selected, the paid amount or currency did not match the order, the payment arrived after the customer had cancelled, or Order Status After Payment is set to On hold.

For developers: before the form is signed, the extension triggers the OpenCart event corvuspay_p_form_params with the form fields and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox CorvusPay 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, Minimum Total and the statuses of the Order statuses section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets CorvusPay through in maintenance mode). If Delete Data is on, the other gateway settings (title, description, Store IDs, Secret Keys, test mode, payment settings, logging) and the log files are removed. If it is off, they are kept for a later re-install. The CorvusPay transaction data is always kept, so the CorvusPay tab of old orders comes back 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 CorvusPay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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