VibeFox Niubiz for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Currency: Peruvian soles (PEN) or US dollars (USD). The payment method is offered only for carts 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
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Niubiz Payment in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure 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.
On install the module creates the order status Niubiz payment on hold. PrestaShop links a new payment module to all currencies and customer groups and to the countries that are active at that moment. You can change this in Payment > Preferences. Check there that PEN or USD is allowed for the module.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when no PEN or USD currency is active in the shop, 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 shop is not PEN or USD, the page tells you that Niubiz is offered only for carts 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.
Niubiz
Enable/Disable: Enable Niubiz payments 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 or debit card (Niubiz). Required: an empty title is not saved and the previous one is kept.
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: uses the Niubiz sandbox (QA) environment, with no real charges. It switches both the API endpoints and the set of credentials below. Default: on. Turn it off for live payments. While it is on, customers see SANDBOX MODE: use Niubiz test cards — no real charges are made. under the payment method and on the payment page.
Sandbox merchant ID: the merchant code of your sandbox account, digits only. Spaces are removed. If the value contains other characters, the page shows an error and keeps the previous value. The other fields are saved.
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, with the same check.
Production API user: the API user of production.
Production API password: the API password of production.
Saved passwords are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Clear saved passwords: tick a password and click Save to remove it. An empty field keeps the saved value.
Payment form
Logo URL: optional HTTPS address of your logo shown in the Niubiz payment form, about 187 × 40 px. Without it the shop name is shown. An address that is not a valid https:// address is refused with an error and the previous value is kept.
Advanced
Debug log: logs the Niubiz API calls to logs/niubiz_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this switch is off. Credentials, 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 module removes its settings and the log. Payment details saved for orders (Niubiz attempts, order notes) and the order status are always kept. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default Credit or debit card (Niubiz)) and places the order. The module requests a Niubiz access token and a payment session for the cart total in the cart currency and opens the Niubiz payment page of your shop. No order exists yet at this point.
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 cart total to open the form again 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 shop, and the module 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 when Niubiz approves the payment and the answer matches the cart. The order is then created and the customer sees the standard order confirmation page.
Declined card: no order is created. 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 is created in Niubiz payment on hold and the confirmation 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 cart, the 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), no order is created and the customer sees Niubiz could not process the payment and your card was not charged. The reason is written to the log.
Cart changed: if the cart total changes after the form was opened (for example in another browser tab), the payment is not authorized and the customer sees Your cart 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 cart total changed, the payment page creates a new session.
Every payment attempt gets a new purchase number: the cart ID followed by a three-digit attempt number (up to 12 characters), because Niubiz requires a unique purchase number for each authorization.
The module takes one-time card payments only. It has no refunds or cancellations from PrestaShop, 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 order yet: the customer is on the payment page and has not paid, or the card was declined or the request was refused. Only the cart exists. Declines and refusals are written to the module log.
Payment accepted: Niubiz approved the payment and the answer matched the cart. The payment is recorded with the Niubiz transaction ID, and a note shows the environment, transaction ID, authorization code, purchase number and the card brand with the masked card number.
Niubiz payment on hold, approved but not matching: Niubiz approved a payment whose purchase number, amount or currency differs from the cart, or whose answer does not contain the amount or currency. The order is not marked paid. If the approval is in the cart currency, the approved amount is recorded as a payment with its transaction ID. The note lists the differences. Check the transaction in the Niubiz console.
Niubiz payment on hold, no definitive answer: Niubiz did not answer clearly, so the card may have been charged. No payment is recorded. The note gives the purchase number. Look it up in the Niubiz console: if the transaction is approved and correct, set the order to Payment accepted; if not, cancel it.
If a second payment is answered for a cart that already has an order, no second order is created. A note on the 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.
Niubiz payment block
The order page shows a Niubiz payment block with the purchase number, the environment (sandbox or production), the transaction ID, the authorization code, the card and the notes of the order. For an order in Niubiz payment on hold the block reminds you to check the purchase number in the Niubiz console. The block is read only.
Refunds
Refunds and cancellations are not available from PrestaShop. Refund or void the transaction in the Niubiz console and update the order manually. The standard PrestaShop refund buttons of the order page do not send money back through Niubiz.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Niubiz Payment is the first block on Modules > Module Manager > VibeFox Niubiz Payment > Configure, 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 shop. Below them are the line Product: presta-payment-niubiz and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 cart currency is PEN or USD. The settings page shows a warning when the credentials or the currencies are wrong. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.
The payment went through, but no order was created: Niubiz has no webhook for this payment form, so the order is created only by the answer to the authorization. If the customer did not finish the form, there is no order. Otherwise look at the Log field on the module page and look up the purchase number in the Niubiz console. If Niubiz answered but the order could not be created (for example, the module was disabled), the customer sees Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., and the module tries again to create the order when the customer opens the payment page 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.
The log shows 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 Niubiz payment on hold: read the notes in the Niubiz payment block. Niubiz did not give a definitive answer, or it approved a payment that does not match the cart. Look up the purchase number in the Niubiz console and set the order to Payment accepted 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.
For developers: if Niubiz asks you to send merchant-specific antifraud fields (MDD), another module can add them with the hook actionNiubizPMerchantDefineData. The cardholder data sent with the payment session can be changed with the hook actionNiubizPCardholderData.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Niubiz Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Niubiz payment attempts (purchase numbers, environment, transaction IDs) and the order status Niubiz payment on hold are always kept as payment history. Existing orders keep their payment notes and transaction IDs.
Niubiz is a trademark of its respective owner. This module is not affiliated with or endorsed by Niubiz.