VibeFox Niubiz for Adobe Commerce — Ayuda

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 extension.

Currency: the currency the customer pays in must be Peruvian soles (PEN) or US dollars (USD). Niubiz charges the order in the order currency. 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. Test (sandbox) credentials come from the Niubiz integrations team, live (production) credentials after Niubiz certifies your integration. The developer documentation is at desarrolladores.niubiz.com.pe. 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 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-niubiz-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/NiubizPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_NiubizPayment 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 Niubiz Payment. 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. Keep Test Mode on Yes and enter the test merchant ID, user and password (see Configuration). Set Enable Niubiz to Yes, click Save Config and make a few test payments with the Niubiz test cards. After Niubiz certifies your integration, enter the live credentials and set Test Mode to No.

The module adds the Credit or debit card (Niubiz) payment method to the Magento checkout. It is off after installation (Enable Niubiz = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates one table for the Niubiz payment attempts.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Niubiz Payment, in the standard Magento configuration form, as one list of fields. 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. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

Some values are refused without stopping the save: the other fields are saved, the old value of that field is kept, and Magento shows a warning that ends with Previous value was kept; other fields were saved. This happens for an empty Title or one longer than 128 characters (Enter a title of 1 to 128 characters.), a merchant ID with characters other than digits (Merchant ID must contain digits only.), a logo address that is not a valid https:// address (Merchant logo must be a valid HTTPS URL.), a Sort order that is not a whole number (Sort order must be a whole number.) and an order total that is not a number of 0 or more (Order total must be zero or greater.).

General

Enable Niubiz: shows or hides Niubiz at checkout. It is shown only when the merchant ID, user and password of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit or debit card (Niubiz). Required, 1 to 128 characters. While Test Mode is Yes, (TEST MODE) is added to the title.

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

Sort order: the position among the payment methods at checkout. A whole number, or empty.

Credentials

Niubiz gives you a merchant ID, an API user and an API password for the test environment and, after certification, for the live environment. Test mode uses only the test credentials, live mode only the live credentials.

Test Mode: when Yes, new payments go to the Niubiz sandbox (QA) with the test credentials and no real charges are made. It switches both the Niubiz servers and the set of credentials. Customers see Test mode: no real payment is taken. under the payment method. Default: Yes. Set it to No for live payments.

Test Merchant ID: the merchant code of your test account, digits only. Spaces are removed.

Test User: the API user of the test environment.

Test Password: the API password of the test environment.

Live Merchant ID: the merchant code of your live (affiliated) account, digits only. Spaces are removed.

Live User: the API user of the live environment.

Live Password: the API password of the live environment.

Magento stores the passwords encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete a saved password, clear the field and click Save Config.

Each payment remembers its mode and merchant ID: a payment that was started in test mode is finished with the test credentials, even if you switch mode in the meantime.

Payment form

Merchant Logo (HTTPS URL): optional https:// address of your logo shown in the Niubiz payment form. Without it the form shows the name of your store view.

Conditions

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

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

Minimum Order Total: offer Niubiz only from this order total, in the base currency of your store. Empty or 0 means no minimum. A comma is accepted as the decimal separator.

Maximum Order Total: offer Niubiz only up to this order total, in the base currency. Empty or 0 means no maximum.

Advanced

Payment status and history: a short reminder of how the module works: PEN and USD only, the payment is authorized on the server, pending orders can reopen their payment session, a missing or mismatched authorization is held for review, refunds are made in the Niubiz console and the payment history is kept on uninstall.

Debug Log: writes the Niubiz API calls and errors to var/log/niubiz_p_debug.log.php in the Magento folder. The file cannot be opened from the web, and it is rotated at 5 MB. Nothing is written while this setting is No. Credentials, tokens, card data and e-mail addresses are never logged. Default: No.

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

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings, its cache and the log (see Uninstall). The license key is always removed. The Niubiz payment history is always preserved. Default: No.

Checkout

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

Your server then requests a Niubiz access token and a payment session for the order total in the order currency, and the customer sees the store page Pay with Niubiz with the text Enter your card details in the secure Niubiz form. If you close it, you can open it again. The button Open secure payment form opens the Niubiz form with your store name or logo, the amount and the currency. JavaScript is required. If the Niubiz form cannot be loaded, the page shows Niubiz could not be loaded. Please try again later.

The customer enters the card in the Niubiz form. Niubiz returns a one-time token to your store, and the module authorizes it on the server with the amount, currency and purchase number of the session, in the mode and with the merchant ID the session was created with. The amount sent by the browser is not used. The payment is charged at once. The order is marked paid only after Niubiz approves it and the answer matches the order: Magento creates the invoice with the Niubiz transaction ID, the order becomes Processing, the order e-mail is sent and the customer sees the standard order success page.

Declined card or refused request: if Niubiz declines the card or refuses the request (for example invalid credentials or a duplicate purchase number), the order is cancelled, the stock goes back and the cart is restored. The customer sees The payment was not completed. Your card was not charged. You can try again. in the cart and can place the order again. The reason from Niubiz is written in a note on the cancelled order.

No definitive answer or mismatch: if Niubiz does not answer clearly (timeout, server error, unreadable answer), or approves a payment whose purchase number, amount or currency differs from the order, the order is put On Hold without an invoice, the order e-mail is sent and the customer sees the success page with Your Niubiz payment requires review. Do not pay again. The order is not authorized again.

Order changed: if the order total or currency changed after the form was opened, or the order is no longer waiting for payment, the card is not charged and a waiting order is cancelled with the cart restored.

Payment could not start: if the payment session cannot be created right after Place Order (for example the license is not active, Niubiz is disabled, the credentials of the current mode are missing or Niubiz cannot be reached), the order is cancelled, the cart is restored and the customer sees Niubiz payment could not be started. Please check the order before trying again.

Session expired: a Niubiz payment session lasts up to 20 minutes. When the session 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. When the Niubiz form times out, the customer returns to the payment page.

Every payment attempt gets a new purchase number: the internal order ID followed by a three-digit attempt number (up to 12 characters), because Niubiz requires a unique purchase number for each authorization. The billing address of the order, the customer's e-mail and, for registered customers, the days since registration are sent with the payment session for the Niubiz antifraud checks.

If the customer leaves the payment page without paying, the order stays in Pending Payment. While the payment page is still open (or reloaded), the customer can open the form again and pay, until Magento cancels it after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If the form was submitted but its result is not known yet, the customer sees Your payment is being confirmed. Do not pay again until its status is known. in the cart.

The module works with the standard Magento checkout. It takes one-time card payments only. It has no refunds or cancellations from Magento, no saved cards, subscriptions or recurring payments, no installments (cuotas) selection, no PagoEfectivo, Yape or other wallets and QR payments, and no webhooks. Orders put on hold because the answer was lost are not re-checked automatically. Niubiz is not offered for orders created in the Admin.

Orders

Order statuses

Pending Payment: the order was placed, but Niubiz has not approved a payment yet: the customer is on the payment page or has left it. There is no invoice.

Processing: Niubiz approved the payment and the answer matched the order. The invoice is created with the Niubiz transaction ID, and a note gives the purchase number and the transaction ID.

On Hold: Niubiz did not give a definitive answer, so the card may have been charged, or it approved a payment that does not match the order. No invoice is created. The note says Niubiz payment requires review. Do not pay again. with the purchase number and the differences found. If an authorization was interrupted on your server, the order is held with a note asking you to check the purchase number. Look up the purchase number in the Niubiz console: if the transaction is approved and correct, release the hold and invoice the order; if not, cancel it and void or refund the transaction in Niubiz.

Canceled: the card was declined, Niubiz refused the request, the order changed before the authorization, the payment could not start, or the order was cancelled in Magento. The note says why.

If the cart already has a paid or held Niubiz payment, a new payment is not authorized. If a second approval still arrives, a note asks you to review the purchase in the Niubiz console. The notes are order comments that the customer does not see.

Niubiz payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once Niubiz has answered, Purchase number, Environment (test or live), Transaction ID, Authorization code, Card brand, Masked card and Authorized amount. The information is shown for old orders too, also when the payment method is disabled.

Refunds

Refunds and cancellations are not sent to Niubiz from Magento. Refund or void the transaction in the Niubiz console, then record it in Magento with a credit memo with Refund Offline, which does not send money back.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Niubiz Payment is the first row of the VibeFox Niubiz Payment 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-niubiz 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, Niubiz 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 Niubiz payment could not be started. Please check the order before trying again. No card is charged. 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: payment sessions already started can still be paid and confirmed, and the payment information of old orders is shown.

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

Niubiz does not appear at checkout: check that the license is active and Enable Niubiz is Yes for the website of the store, and that the merchant ID, user and password of the current mode are set (Test Merchant ID, Test User and Test Password in test mode, the Live fields otherwise). The currency the customer pays in must be PEN or 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.

The payment went through, but the order stays Pending Payment: Niubiz has no webhook for this payment form, so the order is confirmed only by the answer to the authorization. If the customer did not finish the form, nothing was charged. Otherwise turn on Debug Log, look at the Log field and look up the purchase number (in the payment information of the order) in the Niubiz console.

The customer sees Niubiz payment could not be started: the license is not active, Niubiz is disabled, the credentials of the current mode are missing, the order total is 0, or Niubiz did not give an access token or a payment session. Check the merchant ID, user and password of the current mode and that your server can reach the Niubiz API. Turn on Debug Log for details.

The customer sees Niubiz could not be loaded: the Niubiz form script did not load on the payment page. Check that scripts from vnforapps.com are not blocked, for example by a cache or optimization module or by your Content Security Policy settings.

The customer sees Your payment is being confirmed: the form was submitted twice, or another request was processing the same order at that moment. The card is not charged twice. Check the order in the Admin and the purchase number in the Niubiz console before the customer pays again.

Order is On Hold: read the notes of the order. 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, then release the hold and invoice the order, or cancel it.

A setting is not saved: the warning says why, for example Merchant ID must contain digits only. or Merchant logo must be a valid HTTPS URL. The previous value is kept.

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.

For developers: if Niubiz asks you to send merchant-specific antifraud fields (MDD), another module can change them in the event niubiz_p_merchant_define_data. The cardholder data sent with the payment session can be changed in the event niubiz_p_cardholder_data. Both events receive the transport object and the order.

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_NiubizPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings, its cache and the log are removed too. If it is No, the settings are kept for a re-install. The Niubiz payment attempts (purchase numbers, environment, transaction results) are always kept as payment history. Existing orders keep their invoices, payment notes and transaction IDs.

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