VibeFox Niubiz for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

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

PHP: 8.0 or later.

Store currency: Peruvian soles (PEN) or US dollars (USD). For other currencies the payment method 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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_niubiz_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

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

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

5. Keep Sandbox mode on and enter the sandbox merchant ID, API user and API password (see Configuration).

6. Turn on Enable/Disable and make a few test payments with the Niubiz test cards.

7. After Niubiz certifies your integration, enter the production credentials and untick Sandbox mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Niubiz. Above the fields the page warns you when the store currency is not PEN or USD, or when the credentials of the current mode are incomplete (in both cases the payment method is hidden at checkout), and shows Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. while sandbox mode is on. In the list of payment methods, Niubiz is marked as needing setup until the current mode has complete credentials.

General

Enable/Disable: Enable Niubiz payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit or debit card (Niubiz).

Description: the text shown under the payment method at checkout. Default: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Niubiz credentials

Niubiz gives you a merchant ID, an API user and an API password for the sandbox and, after certification, for production. The developer documentation is at desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. Switches both the API endpoints and the set of credentials below. Default: on. Untick it for live payments.

Sandbox merchant ID: the merchant code of your sandbox account, digits only. Spaces are removed. If the value contains other characters, the settings page shows an error and keeps the previous value.

Sandbox API user: the API user of the sandbox.

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.

Payment form

Logo URL: optional HTTPS address of your logo shown in the Niubiz payment form, about 187 × 40 px. Without it the store name is shown. An address that does not start with https:// is refused and the previous value is kept.

Advanced

Debug log: Log API calls writes the Niubiz requests to WooCommerce > Status > Logs, source wcp_niubiz_payment. Errors are always logged. Credentials, tokens, card and customer data are never logged. Default: off.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. Deactivation never deletes anything. Payment details saved on orders are kept. Default: off.

Settings from version 1.0, which had one set of credentials, are moved automatically: to the sandbox fields if test mode was on, otherwise to the production fields.

Checkout

The customer chooses the payment method (by default Credit or debit card (Niubiz)) and places the order. The plugin requests a Niubiz access token and a payment session for the order total and sends the customer to the order payment page of your store. In sandbox mode the checkout and the payment page show SANDBOX MODE: use Niubiz test cards — no real charges are made.

On the payment page the Niubiz payment form opens automatically. The page also has a Pay button with the order total to open the form again, a Cancel order button and a Choose another payment method link. 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 plugin authorizes it on the server with the order's own amount, currency and purchase number. The payment is charged at once. The order is marked paid only when Niubiz approves the payment and the answer matches the order. The customer then sees the order received page.

Declined card: 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 customer sees the order received page with We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you.

Session expired: the payment session lasts up to 20 minutes. When it is used or about to expire, or when the order total or the mode changes, the payment page creates a new session.

Every payment attempt gets a new purchase number: the order ID followed by a three-digit attempt number (up to 12 characters), because Niubiz requires a unique purchase number for each authorization. A customer can pay an unpaid or failed order again from the Pay for order page.

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

The plugin takes one-time card payments only. It has no refunds or cancellations from WooCommerce, 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

Pending payment: the customer was sent to the payment page and has not paid yet.

Processing: Niubiz approved the payment and the answer matched the order. Orders with only virtual downloadable products become Completed, as usual in WooCommerce. The order note shows the environment, transaction ID, authorization code, purchase number and the card brand with the masked card number. The transaction ID of the order is the Niubiz transaction ID.

Failed: the card was declined. The order note shows the Niubiz reason, the action code and the purchase number. The customer can pay again.

On hold, 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. The customer sees Your payment was received and is being reviewed by the store.

On hold, 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 Processing; if not, cancel it.

Cancelled: the customer clicked Cancel order on the payment page, or the order was cancelled by you or by the WooCommerce stock hold timeout.

When Niubiz refuses the request itself (for example a duplicate purchase number, HTTP 406, or invalid credentials), the order status does not change. A note says the card was not charged, and the customer can retry with a new purchase number.

Refunds

Refunds and cancellations are not available from WooCommerce. Refund or void the transaction in the Niubiz console and update the order manually, for example with a manual WooCommerce refund.

License key

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

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started in the Niubiz form are still authorized.

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

Troubleshooting

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 currency is PEN or USD. On the Pay for order page the order currency counts. The settings page shows a warning when the credentials or the currency are wrong.

The payment went through, but the order stays Pending payment: Niubiz has no webhook for this payment form, so the order is updated only by the answer to the authorization. If the order is On hold with a note, look up the purchase number in the Niubiz console. If the order is still Pending payment, the customer did not finish the form; check WooCommerce > Status > Logs, source wcp_niubiz_payment.

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 Your payment session has expired and your card was not charged: the payment page was open too long. The customer tries again on the same page.

Order note 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 On hold with a Niubiz note: read the note. 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 Processing or cancel it.

Error when saving the settings: a merchant ID must contain digits only, and the logo URL must be a valid https:// address. The previous value is kept.

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

For developers: if Niubiz asks you to send merchant-specific antifraud fields (MDD), add them with the niubiz_p_merchant_define_data filter. Keys are MDD plus a number, values up to 100 characters. Other filters: niubiz_p_cardholder_data (cardholder data sent with the payment session), niubiz_p_purchase_number (purchase number of an attempt, 1 to 12 letters or digits, unique per attempt) and niubiz_p_icon (icon of the payment method).

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Niubiz data saved on orders (transaction ID, purchase number, masked card) is payment history and is always kept. Existing orders keep their payment notes and transaction IDs.

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