VibeFox Transbank for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

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

PHP: 8.0 or later.

Store currency: Chilean peso (CLP). Webpay Plus charges whole pesos only, so set Number of decimals to 0 in WooCommerce > Settings > General. In stores with 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_transbank_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Set the store currency to Chilean peso and Number of decimals to 0 in WooCommerce > Settings > General.

4. Open the settings: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, or click Settings under the plugin name on the Plugins page.

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

6. Turn on Enable / Disable and test a payment with Integration (test) mode on, using the test cards from the Transbank developers documentation.

7. To go live, enter your Production Commerce Code and Production API Key Secret, untick Integration (test) mode and save.

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Transbank Webpay Plus. 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 store currency is not CLP (the payment method is hidden), and when CLP prices have decimals (totals are rounded to whole pesos). While integration mode is on, the page shows Integration (test) environment: no real money is charged. After you save, the warnings already follow the new settings. In the list of payment methods, the gateway is marked as needing setup while production is selected without valid credentials.

General

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. Default: Webpay Plus.

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: Use the Transbank integration environment. 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. Untick it to go live.

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

Advanced

Debug log: Log API requests and returns (errors are always logged). Details are written to WooCommerce > Status > Logs, source wcp_transbank_gateway; the field has a view logs link. Errors and warnings are logged even when this option is off. No card data, API keys or full tokens are logged. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (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

The customer chooses the payment method (by default Webpay Plus) and places the order. In integration mode the checkout shows TEST MODE: Integration environment. No real charges. The plugin creates a Transbank transaction for the order 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.

When the customer returns, the plugin 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 store sent for this attempt. The customer then sees the order received page. If the confirmation call fails, for example on a timeout, the plugin asks Transbank for the transaction status. If the status still cannot be known, the order is not changed 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 the customer cancels on Webpay, the Webpay form expires or reports an error, nothing is charged. The order stays awaiting payment and the customer goes back to the Pay for order page 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 customer can pay again from the same page. Each new attempt is a new Webpay transaction.

Each Webpay attempt is confirmed at most once. Reloading the return page, the browser back button or a second return at the same moment never confirm twice and never change the order. If an order no longer needs payment (already paid by another attempt, cancelled or refunded), a late return is not confirmed, so Transbank does not charge it. 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 Webpay cannot start the payment, the customer sees 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 goes to the log.

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

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 the order stays pending; according to Transbank, unconfirmed transactions are not settled. The plugin has no Webpay Plus Mall, Oneclick saved cards, subscriptions, deferred capture or currency conversion.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Webpay and has not paid yet, cancelled, let the form expire, or the payment could not be confirmed yet. A note records each closed attempt with its buy order.

Processing or Completed: Transbank approved the payment. The status is set by WooCommerce: Processing, or Completed for orders with only virtual downloadable products. The order note shows the authorization code, the last four card digits, the buy order, the amount, the payment type and the number of installments. The transaction ID is the Webpay token.

On hold: Transbank authorized a payment that does not match the order (amount, buy order or session id), for example because the order was edited after the payment started. The note lists the differences. Check the Transbank portal and refund or complete the order.

Failed: the payment was rejected. Nothing was charged. The note shows the response code and status.

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

Refunds

The refund button is offered only for orders paid through Webpay. Open the order, click Refund, enter the amount and click Refund via Webpay Plus (the button uses the payment method title). Full and partial refunds are supported in whole pesos. 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. The refund goes to the environment the payment was made in, so in production the production credentials must be set.

Transbank answers with a reversal (REVERSED) or a nullification (NULLIFIED). A successful refund is added to the order notes with the amount, type, authorization code and the balance left at Transbank. If Transbank does not accept the refund, WooCommerce shows the error and no refund is recorded. Refunds made in the Transbank portal are not imported into WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Transbank Webpay Plus. 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, 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. 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 are still confirmed, and refunds work.

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

Webpay Plus does not appear at checkout: check that the license is active, Enable / Disable is on, the store currency is CLP (on the Pay for order page, the order currency) 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.

The payment went through, but the order stays Pending payment: Transbank has no webhook, so the order is confirmed 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. Check the order notes and the log, and 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. The order was not changed and a note was added. The customer can try again in a moment. If the Transbank portal shows the transaction as authorized, confirm it there before shipping.

The customer sees an error when placing the order: turn on Debug log and look at WooCommerce > Status > Logs, source wcp_transbank_gateway. Webpay payments are not available at the moment usually means wrong production credentials. Could not connect to Webpay means Transbank could not be reached. An order in another currency than CLP cannot be paid with Webpay.

Totals and refunds differ by a few pesos: CLP prices have decimals. Webpay charges whole pesos, so totals are rounded. Set Number of decimals to 0.

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.

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.

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, the other options and temporary data of the plugin and its logs (log files, including rotated ones, and database log entries) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. The Transbank data stored on orders is always kept, because it is needed for accounting and refunds. Existing orders keep their payment notes and transaction IDs.

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