VibeFox Transbank 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: Chilean peso (CLP). Webpay Plus charges whole pesos only, so set the precision of the CLP currency to 0 in International > Localization > Currencies. For carts in another currency the payment method is not shown.

Transbank account: for live payments you need a standard Webpay Plus commerce (immediate capture) with its production Commerce Code and API Key Secret. Transbank gives you the Commerce Code when your affiliation is approved and the API Key Secret after the integration validation process (see the Transbank developers documentation). For tests no credentials are needed. Webpay Plus Mall, Oneclick and deferred-capture commerce codes are not supported.

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 Transbank Gateway 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. Turn on Enable / Disable and click Save. Test a payment with Integration (test) mode on, using the test cards from the Transbank developers documentation.

5. To go live, enter your Production Commerce Code and Production API Key Secret, turn off Integration (test) mode and click Save.

No return URL or webhook has to be set up at Transbank. The module sends its return URL with every transaction.

On install the module creates the order status Transbank payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; the CLP currency must stay allowed for the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Transbank Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when production is selected but the production Commerce Code or API Key is missing or invalid (Webpay is then hidden at checkout), when the default currency of the shop is not CLP (the payment method is hidden for other currencies), and when CLP has decimals (totals are rounded to whole pesos). While integration mode is on, the page shows that payments go to the Transbank integration environment with the public test commerce code and that no real money is charged.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus 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: Webpay Plus. Required: saving with an empty title shows Enter a title for the payment method.

Description: the text shown under the payment method at checkout. Default: Pay with credit, debit or prepaid card via Webpay.

Environment and credentials

The section text links to the Transbank developers documentation and explains when Transbank gives you the production credentials.

Integration (test) mode: payments go to the Transbank integration environment with its public test commerce code (597055555532), filled in automatically. The production credentials below are not used and no real money is charged. Default: on. Turn it off to go live. While it is on, customers see TEST MODE: Integration environment. No real charges. above the payment method description.

Production Commerce Code: your production commerce code (Tbk-Api-Key-Id): 12 digits, starting with 5970. If yours has 8 digits, enter it as it is; the module adds the 5970 prefix when you save. Spaces and other characters are removed. The public test commerce codes of Transbank are not accepted in production.

Production API Key Secret: the Tbk-Api-Key-Secret of your production commerce. Keep it secret. Spaces are removed when you save. A saved key is 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 API key: tick Production API Key Secret and click Save to remove the saved key. An empty field keeps the saved value.

Return URL

Return from Webpay: the address Transbank sends the customer back to, shown for reference. Nothing has to be configured at Transbank: the module sends this URL with every transaction. It must be reachable by customers; maintenance mode does not block it.

Advanced

Debug log: logs API requests and returns to logs/wc_tbk_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged, even when this option is off. No card data, API keys or full tokens are 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 the gateway settings and the log. Order data is kept. Default: off.

Test and live

Integration (test) mode decides where new payments go. Each payment remembers its environment: the confirmation and refunds of a payment always go to the environment (integration or production) and with the credentials it was created with, even if you switch the mode later.

Checkout

At the payment step the customer chooses the payment method (by default Webpay Plus, with the Webpay logo) and confirms. The module creates a Transbank transaction for the cart total in whole pesos (a total with decimals is rounded to the nearest peso) and sends the customer to a short page Redirecting to Webpay. Please wait..., which forwards to the Webpay form. Without JavaScript the customer clicks Proceed to Webpay. On Webpay the customer pays by credit, debit or prepaid card. No order exists yet at this point.

When the customer returns, the module confirms (commits) the transaction with Transbank server-to-server. The order is marked paid only after Transbank confirms it: the answer must be approved, and the amount, buy order and session must match what the shop sent for this attempt. The order is then created and the customer sees the standard order confirmation page with Your Webpay payment has been received. For an order on hold the page shows Your Webpay payment was received and is being reviewed by the shop.

If the confirmation call fails, for example on a timeout, the module asks Transbank for the transaction status. If the status still cannot be known, no order is created and the customer sees We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. If another request is confirming the same cart at that moment, or Transbank approved the payment but the order could not be created yet, the customer sees a Payment confirmation page with Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. and a Check again button. The order is then created from the stored answer, without a second confirmation.

If the customer cancels on Webpay, or the Webpay form expires or reports an error, nothing is charged. The customer is back at checkout with a message, for example You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. A rejected card shows Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. The cart is kept, and each new attempt is a new Webpay transaction.

If the cart changed after the payment started (for example, in another tab, or a voucher in the cart stopped being valid and PrestaShop removed it), the transaction is not confirmed, so Transbank does not charge it. The customer sees Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. If the cart already has an order (paid by another attempt or another payment method), a late return is not confirmed either, and the customer sees This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged. if that order is not paid.

If Webpay cannot start the payment, the customer stays at checkout with a short message, for example Could not connect to Webpay. Please try again in a moment. or Webpay payments are not available at the moment. Please choose another payment method. The technical reason is written to the log.

The return from Webpay works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Transbank has no payment webhook: the result is processed when the customer comes back from Webpay. If the customer closes the browser on Webpay and never returns, the transaction is not confirmed and no order is created; according to Transbank, unconfirmed transactions are not settled. The module has no Webpay Plus Mall, Oneclick saved cards, subscriptions, deferred capture or currency conversion.

Orders and refunds

Order statuses

No order yet: the customer was sent to Webpay and has not paid, cancelled, let the form expire, the card was rejected, or the payment could not be confirmed yet. Only the cart exists.

Payment accepted: Transbank approved the payment. The payment is recorded with the Webpay token as the transaction ID, and a note shows the authorization code, the last four card digits, the buy order, the amount, the payment type and the number of installments.

Transbank payment on hold: Transbank authorized a payment that does not match the order (amount, buy order or session), or a voucher in the cart stopped being valid after Transbank approved the payment and PrestaShop removed it. The payment is recorded with the amount Transbank charged, and the note lists the differences. Check the Transbank portal and fulfil the order or refund the payment.

Refunded: the payment was fully refunded through the module.

If Webpay returns a payment for a cart that already has an order, the payment is not confirmed and a note on that order asks you to check the Transbank portal if the customer reports a charge. Existing orders are not affected by later attempts.

Transbank Webpay Plus block

The order page shows a Transbank Webpay Plus block with the buy order and its environment, the payment status, the authorization code, the card and payment type with the number of installments, the amount charged and refunded, an Integration badge for test payments, the refund history, the Webpay attempts of the cart and the Transbank notes of the order.

Refunds

In the Transbank Webpay Plus block enter the amount in CLP (the amount not refunded yet is filled in), optionally a reason, and click Refund via Transbank. Confirm the question Refund this amount via Transbank? Full and partial refunds are supported in whole pesos. You need the right to edit orders; access to the Modules pages is not needed. A partial amount with decimals is refused with Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. The last remainder of an order total with decimals is rounded like the charge. Refunds are made up to the amount Transbank charged, so after a mismatch you can refund what the customer actually paid. The refund goes to the environment the payment was made in, so for a production payment the production credentials must be set.

Transbank answers with a reversal (REVERSED) or a nullification (NULLIFIED). A successful refund is added to the refund history and the notes with the amount, type, authorization code and the balance left at Transbank. A full refund sets the order to Refunded. A partial refund does not change the status. If Transbank does not accept the refund, the block shows the error and no refund is recorded.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Transbank. Refunds made in the Transbank portal are not imported into PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Transbank Gateway is the first block on Modules > Module Manager > VibeFox Transbank Gateway > 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-transbank 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, Webpay Plus 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 the customer returns from Webpay, and refunds from the order page work.

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

Webpay Plus does not appear at checkout: check that the license is active, Enable / Disable is on, the cart currency is CLP and, with integration mode off, that a valid Production Commerce Code (12 digits, starting with 5970) and Production API Key Secret are saved. The settings page shows a warning for each missing condition. In Payment > Preferences check that the module is allowed for CLP, the customer's country and the customer's group.

The payment went through, but no order was created: Transbank has no webhook, so the order is created only when the customer returns from Webpay. If the customer closed the browser on Webpay, the transaction was not confirmed and, according to Transbank, is not settled. Turn on Debug log, look at the Log field and check the transaction in the Transbank portal.

The customer sees We could not confirm your Webpay payment with Transbank: the confirmation call failed and the status could not be checked. No order was created and the reason is in the log. The customer can try again in a moment. If the Transbank portal shows the transaction as authorized, contact the customer before they pay again.

The customer sees Your cart changed after the Webpay payment was started: the cart total differed from the transaction, for example because of a change in another tab or an expired voucher. Nothing was charged; the customer pays the new total.

The customer sees an error when choosing Webpay Plus: turn on Debug log and look at the Log field on the module page. Webpay payments are not available at the moment usually means wrong production credentials. Could not connect to Webpay means Transbank could not be reached. Transbank Webpay only supports payments in CLP (Chilean Peso) means the cart is in another currency.

Totals and refunds differ by a few pesos: the CLP currency has decimals. Webpay charges whole pesos, so totals are rounded. Set the CLP precision to 0 in International > Localization > Currencies.

Order is Transbank payment on hold after payment: read the notes in the Transbank Webpay Plus block (see Order statuses), then fulfil the order or refund the payment.

Refund fails with The production Commerce Code / API Key are missing: the payment was made in production and the production credentials are not saved. Enter them and try again.

Refund fails with Transbank refused the refund or Transbank did not approve the refund: Transbank did not accept it; the message shows the reason or the type and response code it returned. Nothing was refunded. Check the transaction in the Transbank portal.

Refund fails with Another request is processing this order: the order was being refunded or confirmed at the same moment. Try again in a moment.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Transbank Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Webpay attempts and refunds of orders and the order status Transbank payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

Transbank and Webpay are trademarks of their respective owner. This module is not affiliated with or endorsed by Transbank.