VibeFox Niubiz 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: Peruvian soles (PEN) or US dollars (USD) must be enabled in System > Localisation > Currencies. The payment method is offered only when the customer pays in one of these currencies. For other currencies it is hidden at checkout.

Niubiz account: Niubiz issues a merchant ID (código de comercio), an API user and an API password for each environment. Sandbox credentials come from the Niubiz integrations team, production credentials after Niubiz certifies your integration. No webhook has to be set up: Niubiz answers the authorization at once.

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_niubiz_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_niubiz_payment.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_niubiz_payment-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 Niubiz Payment 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. Keep Sandbox mode on and enter the sandbox merchant ID, API user and API password (see Configuration).

5. Turn on Enable/Disable, click Save and make a few test payments with the Niubiz test cards.

6. After Niubiz certifies your integration, enter the production credentials and turn off Sandbox mode.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_niubiz_payment.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 Niubiz Payment, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Niubiz credentials and test the payments as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions.

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 Niubiz Payment > 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 no PEN or USD currency is enabled in the store, or when the credentials of the current mode are incomplete (in both cases the payment method is hidden at checkout). If the default currency of the store is not PEN or USD, the page tells you that Niubiz is offered only when the customer pays in PEN or USD. While sandbox mode is on, the page shows Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, a wrong value is not saved: the page shows an error above the settings, the field returns to its previous value and the other fields are saved. This applies to an empty Title or one longer than 128 characters, a merchant ID that is not digits only, a logo URL that is not https://, a Sort Order that is not a whole number and a Total that is not a number of 0 or more.

Niubiz

Enable/Disable: turns Niubiz payments 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 or debit card (Niubiz). Required, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

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

Geo Zone: offer Niubiz only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones. On OpenCart 4, when the store asks for no payment address, the shipping address is used.

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

Niubiz credentials

Niubiz gives you a merchant ID, an API user and an API password for the sandbox (QA) and, after certification, for production. A payment already started is always authorized with the credentials of its own mode.

Sandbox mode: uses the Niubiz sandbox, with no real charges. It switches both the API endpoints and the set of credentials below. Default: on. Turn it off to take real payments with the production credentials. While it is on, customers see SANDBOX MODE: use Niubiz test cards — no real charges are made. at the Confirm Order step and on the payment page.

Sandbox merchant ID: the merchant code (código de comercio) of your sandbox account, digits only. Spaces are removed.

Sandbox API user: the API user of the sandbox, usually an e-mail address.

Sandbox API password: the API password of the sandbox.

Production merchant ID: the merchant code of your production (affiliated) account, digits only.

Production API user: the API user of production.

Production API password: the API password of production.

Saved passwords are never shown again and never sent to the browser. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To remove a saved password, tick Clear the saved password on save under the field and click Save.

Payment form

Logo URL: optional address of your logo shown in the Niubiz payment form. It must be an https:// address. Leave it empty to show the store name.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Niubiz has answered the authorization. Each field below lists your OpenCart order statuses.

Order Status After Payment: Niubiz approved the payment and the purchase number, amount and currency match the order. Default: Processing.

On Hold Status: Niubiz approved a payment that does not match the order, or did not give a definitive answer, so the card may have been charged. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Advanced

Debug log: writes the Niubiz API requests and payment steps to niubiz_p_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 niubiz_p_debug.old.log.php. Errors and warnings are always logged, even when this switch is off. Passwords, tokens, card and customer data are never logged. 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 extension removes the gateway settings and the log. The Niubiz payment details of orders (purchase numbers, transaction IDs) are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API passwords are not exported.

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

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit or debit card (Niubiz)). At the Confirm Order step the customer sees your description and the note You will complete the payment in the secure Niubiz payment form. OpenCart creates the order at this step, still without a status. 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. When the customer clicks Confirm Order, the extension requests a Niubiz access token and a payment session for the order total in the order currency and opens the Niubiz payment page of your store. If the session cannot be created, the customer stays at the Confirm Order step with a short message, for example We could not connect to Niubiz. Please try again in a few minutes.

On the payment page the Niubiz payment form opens automatically. The page says Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. It also has a Pay button with the order total to open the form again and a Choose another payment method link back to the checkout. JavaScript is required. If the Niubiz form cannot be loaded, the page shows The Niubiz payment form could not be loaded. Please reload the page or try again later.

The customer enters the card in the Niubiz form. Niubiz returns a one-time token to your store, and the extension authorizes it on the server with the amount, currency and purchase number of the session, in the environment the session was created in. The payment is charged at once. The order is marked paid only after Niubiz confirms it and the answer matches 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.

Declined card: the order stays without a status and a note is added to it. The customer returns to the payment page with Your payment was declined: and the reason from Niubiz, and can try again with the same or another card. The form does not reopen over the message; the customer clicks Pay.

No answer from Niubiz: if Niubiz does not give a definitive answer (timeout, server error, unreadable answer), the order gets the On Hold Status and the success page shows We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. If Niubiz approved a payment that does not match the order, the success page shows Your payment was received and is being reviewed by the store. We will contact you if anything else is needed.

Request refused: if Niubiz refuses the request itself (for example invalid credentials or a duplicate purchase number), the order stays without a status, a note is added, and the customer sees Niubiz could not process the payment and your card was not charged. If the Niubiz API cannot be reached at that moment, the customer sees We could not connect to Niubiz and your card was not charged. Please try again in a few minutes.

Order changed: if the order total no longer matches the session when the form is submitted, the payment is not authorized and the customer sees Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again.

Session expired: a Niubiz payment session lasts up to 20 minutes. When it was already used, has less than 5 minutes left, belongs to another mode or merchant ID, or the order total changed, the payment page creates a new session.

Every payment attempt gets a new purchase number: the order number followed by a three-digit attempt number, because Niubiz requires a unique purchase number for each authorization. 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, so after a declined card the customer pays the same order with a new purchase number. A cart that is already paid is not paid again: the customer is taken to the success page of the paid order instead.

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), the customer is sent back to the checkout with Your previous order was cancelled or its payment failed. Please confirm the order again., and the next Confirm Order pays a new order. If that order already has a status and the cart now has other products or quantities, the message is Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. On OpenCart 4 the messages that send the customer back to the checkout, such as The Niubiz payment could not be found. Please confirm your order again., are shown above the checkout page.

The payment page, the answer of the Niubiz form and the return to the store also work 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 them.

The extension takes one-time card payments only. It has no refunds or cancellations from OpenCart, no saved cards, subscriptions or recurring payments, no installments (cuotas) selection and no PagoEfectivo, Yape or other wallets and QR payments. Orders put on hold because the answer was lost are not re-checked automatically.

Orders

Order statuses

No status (missing order): the customer is on the payment page and has not paid, or the card was declined or the request was refused. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. Declines and refusals are added to the order notes.

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, and a later payment still confirms it.

Order Status After Payment (default Processing): Niubiz approved the payment and the answer matched the order. A note shows the environment, transaction ID, authorization code, purchase number and the card brand with the masked card number.

On Hold Status (default Pending), approved but not matching: Niubiz approved a payment whose purchase number, amount or currency differs from the order, or whose answer does not contain the amount or currency. The order is not marked paid. The note lists the differences. Check the transaction in the Niubiz console.

On Hold Status (default Pending), no definitive answer: Niubiz did not answer clearly, so the card may have been charged. The note gives the purchase number. Look it up in the Niubiz console: if the transaction is approved and correct, set the order to the paid status; if not, cancel it.

If a second payment is answered for a cart that is already paid, no second status is set. A note on the paid order gives the purchase number, transaction ID and amount, so you can check it in the Niubiz console and refund or void it if needed.

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

VibeFox Niubiz Payment tab

In Sales > Orders open an order paid with Niubiz. At the bottom of the order page, next to History and Additional, the VibeFox Niubiz Payment tab shows the purchase number, the environment (sandbox or production), the Niubiz answer, the transaction ID, the authorization code, the card, the amount (and the amount approved by Niubiz), any problems found, the number of attempts and the Niubiz notes of the order. For an order in the on hold status the tab reminds you to check the purchase number in the Niubiz console. The tab is read only and is shown to users who have access to the extension.

Refunds

Refunds and cancellations are not available from OpenCart. Refund or void the transaction in the Niubiz console and update the order status manually. Product returns in Sales > Returns do not send money back through Niubiz.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Niubiz Payment is the first block on Extensions > Extensions > Payments > VibeFox Niubiz Payment > 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-niubiz 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, Niubiz 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 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

Niubiz does not appear at checkout: check that the license is active, Enable/Disable is on, the merchant ID, API user and API password of the current mode are filled in (sandbox fields in sandbox mode, production fields otherwise) and the customer pays in PEN or USD. The settings page shows a warning when the credentials or the currencies are wrong. Also check 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 without a status: Niubiz has no webhook for this payment form, so the order gets its status only from the answer to the authorization. If the customer did not finish the form, nothing was paid. Otherwise look at the Log field on the extension page and look up the purchase number in the Niubiz console. If Niubiz answered but the 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., and the extension tries again to set the status when the customer opens the payment page or confirms the cart again.

The customer sees We could not connect to Niubiz: the access token could not be obtained. Check the API user and API password of the current mode and that your server can reach the Niubiz API. Turn on Debug log for details.

The customer sees We could not start the Niubiz payment: Niubiz did not create the payment session. Check the merchant ID of the current mode and the log.

The customer sees This payment attempt was already processed: the same form was submitted twice. The customer starts the payment again on the payment page; the card is not charged twice.

The customer sees This order is already being paid: another request is authorizing the same cart at this moment. The customer waits a moment and checks the e-mail before trying again.

A note says Niubiz reported a duplicate authorization: Niubiz already knows this purchase number. Check it in the Niubiz console; the customer can retry with a new purchase number.

Order is in the on hold status: read the notes in the VibeFox Niubiz Payment tab. Niubiz did not give a definitive answer, or it approved a payment that does not match the order. Look up the purchase number in the Niubiz console and set the order to the paid status or cancel it.

Error when saving the settings: a merchant ID must contain digits only, the logo URL must be a valid https:// address and the title must not be empty or longer than 128 characters. The previous value is kept.

For developers: if Niubiz asks you to send merchant-specific antifraud fields (MDD), another extension can add them with the OpenCart event niubiz_p_merchant_define_data. The cardholder data sent with the payment session can be changed with the event niubiz_p_cardholder_data.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Niubiz Payment. 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 and its startup action, which lets the payment page, the answer of the Niubiz form and the return through in maintenance mode). If Delete data on uninstall is on, the other gateway settings (title, description, sandbox mode, credentials, logo, logging) and the log are removed. If it is off, they are kept for a later re-install. The Niubiz payment attempts (purchase numbers, environment, transaction IDs) are always kept as payment history. 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 Niubiz Payment in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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