VibeFox Transbank for Adobe Commerce — Aide

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: Chilean peso (CLP). Webpay Plus charges whole pesos only. For orders in another currency the payment method is not shown. Your store can have another base currency, as long as the customer pays in CLP.

Transbank account: for live payments you need a standard Webpay Plus commerce (immediate capture) with its production commerce code and API key (the Tbk-Api-Key-Id and Tbk-Api-Key-Secret). Transbank gives you the commerce code when your affiliation is approved and the API key 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.

Public website: the return address of your store must be reachable by your customers' browsers. Nothing has to be configured at Transbank.

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-transbank-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/TransbankPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_TransbankPayment 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 Transbank Gateway. 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. Set Enable to Yes and click Save Config. Test a payment with Integration mode = Yes, using the test cards from the Transbank developers documentation. To go live, enter your Production commerce code and Production API key, set Integration mode to No and click Save Config.

The module adds the Webpay Plus payment method to the Magento checkout. It is off after installation (Enable = No). No return URL or webhook has to be set up at Transbank: the module sends its return URL with every transaction. The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Webpay payment attempts and the refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Transbank Gateway, in the standard Magento configuration form. 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. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page. The fields form one list; below they are grouped by purpose in the order they appear.

If a value is wrong, Magento shows an error and nothing on the page is saved: Enter a title for the payment method (up to 128 characters)., Sort order must be a whole number., or Order total must be non-negative. for Minimum order total and Maximum order total (use a point as the decimal separator, for example 9.99).

Return URL and notices

Below the license block the page shows Return URL is sent with each payment; no webhook configuration is needed. and the return URL of the default store view, which looks like https://your-store/wcptransbankgateway/checkout/back/. It is shown for reference only. Each payment sends the return URL of the store view of its order. When Enable is Yes in the Default Config, the page also shows Webpay charges CLP only. Totals are rounded to whole Chilean pesos., the warning Webpay production credentials are missing or invalid. when integration mode is off and the production commerce code or API key is missing or invalid (Webpay is then hidden at checkout), and Integration mode uses public test credentials. No real money is charged. while integration mode is on.

General

Enable: shows or hides Webpay Plus at checkout. It is shown only for orders in CLP and, with integration mode off, only when valid production credentials are saved. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Webpay Plus. Required, at most 128 characters.

Description: text shown in the payment method list at checkout, when the customer selects Webpay Plus. Default: Pay with credit, debit or prepaid card via Webpay.

Environment and credentials

Integration mode: payments go to the Transbank integration environment with its public test commerce code (597055555532), filled in automatically. The production fields below are not used and no real money is charged. Default: Yes. Set it to No to go live. While it is on, customers see INTEGRATION MODE - no real payment. Do not ship test orders. under the payment method.

Production commerce code: your production commerce code (Tbk-Api-Key-Id): digits only, 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: with such a code Webpay Plus is hidden at checkout in production.

Production API key: the Tbk-Api-Key-Secret of your production commerce. Spaces are removed when you save. Magento stores the key encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.

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

Advanced

Debug log: writes Webpay requests and returns to var/log/wc_tbk_debug.log.php in the Magento folder. The file cannot be opened from the web, and it is rotated at 5 MB. Card numbers, API keys, e-mail and IP addresses and full tokens are not logged. While it is No, nothing is logged. Default: No.

Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Webpay payment and refund records always stay. Default: No.

Conditions

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

Payment from specific countries: offer Webpay Plus only for billing addresses in these countries.

Minimum order total: offer Webpay Plus only from this order total, in the base currency of your store. Empty or 0 means no minimum.

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

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

Log

The last row of the group shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Webpay Plus) and sees the description and the note You will be redirected to Transbank to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Transbank transaction for the order total in whole pesos (a total with cents is rounded to the nearest peso) and shows a short page Redirecting to Webpay, which forwards the customer to the Webpay form. Without JavaScript the customer clicks Continue to Webpay. On Webpay the customer pays by credit, debit or prepaid card. Reloading that page opens the same Webpay transaction.

When the customer returns, the module confirms (commits) the transaction with Transbank server-to-server, with the credentials of the environment of the payment. Before that it checks that the order is still waiting for payment and that its total in whole pesos is still the amount sent to Webpay. 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. Magento then creates the invoice with the Webpay token as the transaction ID and sends the order e-mail. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page; the payment is confirmed all the same.

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, or the payment needs a review, the order stays as it is and the customer sees the page Webpay payment confirmation with Payment is not confirmed or requires review. Check its status before trying another payment. with the order number and a Check again link. A later check asks Transbank again and confirms the payment without charging it twice.

If the customer cancels on Webpay, the Webpay form expires or reports an error, or Transbank rejects the card, nothing is charged. The order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Webpay payment did not complete. Your cart has been restored. The same happens when the order total no longer matches the amount sent to Webpay: the transaction is not confirmed, so it is not charged.

If Webpay cannot start the payment and it is certain that no Webpay transaction exists, for example because Transbank refused the request (wrong production credentials), the production credentials are missing or the order is not in CLP, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Webpay could not start the payment. Your cart has been restored. Please try again or choose another payment method. A note on the order gives the reason. If the result of the start request is unknown, for example Transbank did not answer, the order stays in Pending Payment, the module does not start another Webpay transaction for this order and the customer is sent to the cart with Webpay could not start this payment. Review the pending order before trying again. Turn on Debug log to see the reason.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), a later return from Webpay is not confirmed, so Transbank does not charge it. A note is added to the order. If the transaction had already been confirmed, the order stays Canceled and a note asks for a review; no invoice is created.

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 in Pending Payment; according to Transbank, unconfirmed transactions are not settled. The module works with the standard Magento checkout. It has no Webpay Plus Mall, Oneclick saved cards, subscriptions, deferred capture or currency conversion. Webpay Plus is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Webpay, but the payment has not been confirmed yet. There is no invoice.

Processing: Transbank approved the payment and it matches the order. The invoice is created 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 in CLP, the payment type and the number of installments.

On Hold: Transbank approved a payment that does not match the order (amount, buy order or session). No invoice is created, and the note lists the differences. Check the Transbank portal, then fulfil the order or refund the payment with the form in Webpay payment history.

Canceled: the customer cancelled or did not complete the payment, the card was rejected, the payment could not be started, the order total changed before the confirmation, or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If Webpay returns a payment for an order whose cart is already paid by another order, the transaction is not confirmed and a note is added. The notes are order comments that the customer does not see.

Webpay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once the payment is approved, Webpay environment, Webpay authorization and Webpay card last four. The customer sees only the title. The Information tab also shows Webpay payment history: every Webpay attempt of the order with the buy order, the masked token, the environment, the status and the requested and paid amount in CLP, followed by the Webpay refund history. It is shown for old orders too, also when the module is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The refund is requested from Transbank for the credit memo total in whole pesos. Full and partial refunds are supported, up to the amount Transbank charged minus the earlier refunds. A partial amount with cents is refused with Webpay refunds must be whole Chilean pesos, except the final order remainder. The last remainder of an order total with cents is refunded as the pesos still left of the charge. The refund goes to the environment the payment was made in, so for a production payment the production credentials must be set. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Transbank.

Transbank answers with a reversal (REVERSED) or a nullification (NULLIFIED). When the refund succeeds, Magento creates the credit memo and the refund is added to the Webpay refund history with its amount. A full refund closes the order. If Transbank refuses the refund or the result is not known, Magento shows Webpay refund was not confirmed. Reconcile in the merchant panel before retrying. and the credit memo is not created. After a refusal you can try again. A refund whose request got no clear answer from Transbank stays unconfirmed and blocks further online refunds of that payment: Magento shows Earlier Webpay refund is unconfirmed. Reconcile before another request. Check the refund in the Transbank portal and refund the rest there, then create a credit memo with Refund Offline.

For a payment that needs manual review (On Hold after a mismatch, a payment confirmed for a cancelled order), the Webpay payment history shows the field Review refund amount (CLP) and the button Refund held Webpay payment. Enter the amount in whole pesos and click the button. You need the right to create credit memos. The money is returned through Transbank without a credit memo; Magento shows Transbank review refund accepted. and a note with the amount, type, authorization code and the balance left at Transbank is added to the order. Refunds made in the Transbank portal are not imported into Magento.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Transbank Gateway is the first row of the VibeFox Transbank Gateway 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-transbank 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, Webpay Plus is not shown to customers at checkout. If a payment is started anyway, no Webpay transaction is created, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. 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: payments already started are still confirmed when the customer returns from Webpay, and refunds work.

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

Webpay Plus does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the order currency is CLP. With Integration mode = No, check that a valid Production commerce code (12 digits, starting with 5970, not a public test code) and Production API key are saved; the settings page then shows Webpay production credentials are missing or invalid. 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: 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 that the return URL opens from the internet and is not blocked by password protection, a firewall or Magento maintenance mode. Turn on Debug log, look at the log at the bottom of the group and check the transaction in the Transbank portal.

The customer sees Payment is not confirmed or requires review: the confirmation call failed and the status could not be checked, or the payment needs a review. The customer can click Check again in a moment. If the Transbank portal shows the transaction as authorized, contact the customer before they pay again.

The return page answers Payment is being updated. Retry shortly.: another request was confirming the same order at that moment. Reload the page. The answers Unknown Webpay return. and Missing Webpay fields. mean that the return does not belong to a payment of this store.

The customer is back in the cart with Webpay could not start the payment: Transbank refused to create the transaction, or the production credentials are missing. The order of that attempt is cancelled. Turn on Debug log, look at the log and check the production credentials.

The customer sees Webpay could not start this payment. Review the pending order: Transbank did not answer the start request, so it is not known whether a Webpay transaction exists. The order stays in Pending Payment. Check the transaction in the Transbank portal, then cancel the order or let the Magento cron cancel it after the Pending Payment Order Lifetime.

Totals and refunds differ by a few pesos: the order total has cents, for example because prices are converted from another base currency or tax is added. Webpay charges whole pesos, so totals are rounded. Use whole peso prices.

Order is On Hold after payment: read the order notes and the Webpay payment history (see Order statuses), then fulfil the order or refund the payment.

Refund fails with Original Webpay environment keys are missing.: the payment was made in production and the production credentials are not saved. Enter them and try again.

Refund fails with Refund exceeds actual paid funds or order total.: the refund is larger than the amount Transbank charged minus the earlier refunds, or than the order total.

Refund fails with Accepted Webpay refund has no native Credit Memo. Reconcile first.: Transbank accepted an earlier refund, but its credit memo was not created. Check the refunds in the Transbank portal, record them with Refund Offline and refund the rest there.

Refund fails with Payment is being updated.: the order was being refunded or confirmed at the same moment. Try again in a moment.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; use the form in Webpay payment history.

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.

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

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

The license key and license status are always removed. If Delete settings on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Webpay payment and refund records are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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