VibeFox Braintree for Adobe Commerce — Ajuda

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.

Braintree account: you need the Merchant ID, Public Key and Private Key of your Braintree account. They are in the Braintree Control Panel (sandbox: sandbox.braintreegateway.com, live: www.braintreegateway.com) under the gear icon, API, API Keys. Sandbox and live accounts have different keys. 3-D Secure must be enabled for your Braintree merchant account, unless you set 3-D Secure to Disabled. No webhook is needed: card payments are confirmed immediately.

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

2. Run bin/magento module:enable Vibefox_BraintreePayment 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 Braintree 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. Copy the Merchant ID, Public Key and Private Key from the Braintree Control Panel into the sandbox or live fields of API Credentials. Set Enable to Yes and click Save Config. Keep Sandbox Mode at Yes and place a test order with a Braintree sandbox test card. Then set Sandbox Mode to No to take real payments with the live credentials.

The module adds the Credit / debit card payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Braintree transactions and the operations sent to Braintree (charges, captures, voids and refunds).

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Braintree 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 Data on Uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Braintree: enter a title of 1 to 128 characters.); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

The Braintree Setup row at the top of the group reminds you to create sandbox and production API credentials in the Braintree Control Panel and how to map currencies to merchant accounts. When Enable is Yes, it also warns Braintree is enabled but the selected environment credentials are incomplete. when the Merchant ID, Public Key or Private Key of the selected environment is missing (Braintree is then hidden at checkout), and, with Authorize only, Authorization reserves funds only. Capture Online from the native Invoice before fulfilment.

General

Enable: shows or hides Braintree at checkout. It is shown only when the Merchant ID, Public Key and Private Key of the selected environment are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit / debit card. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely with your credit or debit card via Braintree.

API Credentials

Log in to the Braintree Control Panel (sandbox or live), click the gear icon, then API and API Keys. The public and private keys are listed there, and the Merchant ID is shown on the same page. Sandbox and live credentials are kept separately; the selected environment uses only its own.

Sandbox Mode: uses the Braintree sandbox (test payments, no real money). Default: Yes. Set it to No to take real payments with the live credentials. Captures, voids and refunds always use the environment the order was paid in.

Sandbox Merchant ID and Live Merchant ID: the Merchant ID of the sandbox or live account.

Sandbox Public Key and Live Public Key: the public key of that account.

Sandbox Private Key and Live Private Key: the private key of that account. Magento stores the private keys 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 a saved key, clear the field and click Save Config.

Sandbox Merchant Account ID(s) and Live Merchant Account ID(s): optional. Braintree charges in the currency of the merchant account. Leave empty to use your default merchant account, enter one ID (for example account_eur) or one per currency: EUR=account_eur, USD=account_usd. The account currency must match the order currency. If the charged currency does not match, the transaction is voided automatically and the customer is not charged.

Payment

Transaction Type: how the card is charged.

3-D Secure: 3-D Secure 2 (Strong Customer Authentication) is mandatory for most card payments in the EEA and UK. It must also be enabled for your Braintree account (contact Braintree support if payments fail with a 3-D Secure configuration error).

As the field comment says, authentication is also checked on the server, not only in the browser, before the card is charged.

Native Restrictions

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

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

Minimum Order Total: offer Braintree only from this order total, in the base currency of your store. Empty means no minimum.

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

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

Advanced

Debug Log: also logs payment steps and API calls to var/log/wc_btg_debug.log.php in the Magento folder. Errors are always logged, even when this is No. The file cannot be opened from the web and never contains API keys, card numbers or payment tokens. Default: No.

Delete Data on Uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Braintree transactions and operations always stay, so orders paid before can still be captured, voided or refunded after a re-install. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default Credit / debit card) and sees the description and the Braintree card form with the card number, expiry date, security code and cardholder name. The form is loaded from Braintree when the customer selects the method and is created for the current order total; if the total changes, the form is reloaded. With 3-D Secure on, the customer completes the bank's verification after clicking Place Order; the order total, e-mail and billing address are passed to it.

Magento then places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module charges the one-time token through the Braintree API for the order total in the order currency, with the cart number as the order ID in Braintree. The charged amount and currency are checked against the order. When Braintree accepts the payment, Magento creates the invoice with the Braintree transaction ID (Sale) or records the authorized amount (Authorize only), sends the order e-mail, and the customer sees the standard order success page.

If the payment fails, the order stays in Pending Payment and the customer goes to the Braintree payment page of the store with the order number and the reason, for example Your card was declined. Use another card or contact your bank., 3-D Secure authentication failed. Try another card., 3-D Secure authentication is required. Enter your card details again. or The card security code or billing address could not be verified. Check your details. The page says Enter your card details again to pay this pending order. and shows the card form with Pay now. Back to cart cancels the unpaid order (the stock goes back) and restores the cart, so the customer can choose another payment method. The reason is written to the module log.

If the charged currency or amount does not match the order, the transaction is voided, the order is cancelled and the customer sees The Braintree amount or currency did not match. The transaction was voided. Check the merchant account settings.

A cart is never charged twice. A second request while the payment is running is refused with Braintree: another operation on this cart is running. Try again. A payment token is used only once. If the card was charged but Magento could not complete the order, the payment page shows Your payment is confirmed. Complete the order without another charge. and the button Complete order. If the answer from Braintree was lost, the customer sees The Braintree result is uncertain. Contact the store before paying again. and no new charge is sent for that cart until you check the transaction in the Braintree Control Panel.

An unpaid order in Pending Payment can be cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). An order whose Braintree result is uncertain or needs review is not cancelled. In the Admin, Magento shows This Braintree payment needs reconciliation before cancellation. No new payment was sent. The cron leaves such an order in Pending Payment with a note asking you to check the Braintree Control Panel, and goes on cancelling the other expired orders. If Braintree charged or authorized the card but the order was not updated, the cron does not cancel the order: it registers the payment, and the order goes to Processing (with an invoice for a sale, with reserved funds for Authorize only).

The module works with the standard Magento checkout. It takes card payments only. It has no saved cards, no subscriptions or recurring payments, no PayPal, Venmo, Apple Pay, Google Pay or local payment methods, no multishipping checkout and no Braintree webhooks. Braintree is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but the card has not been charged yet or the payment failed. There is no invoice.

Processing: the card was charged (Sale): the invoice is created with the Braintree transaction ID, and a note shows the amount and the transaction. With Authorize only the order is also Processing, but only the authorized amount is recorded, without an invoice; the note asks you to use Invoice with Capture Online before fulfilment.

On Hold: the payment needs review: Braintree returned an unexpected transaction status or transaction, or a charge in the wrong currency or amount could not be voided automatically. No invoice is created. The note shows the actual and the expected amount and the transaction. Reconcile it in the Braintree Control Panel before fulfilment.

Canceled: the customer went back to the cart without paying, a wrong charge was voided automatically, an authorization was voided, or the order was cancelled in Magento.

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

If a payment arrives for an order that is already cancelled, or for a cart that was already paid with another order, no invoice is created and a note asks you to reconcile the payment in the Braintree Control Panel. The notes are order comments that the customer does not see.

Braintree payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Braintree payment, Braintree transaction, Environment (sandbox or production), Payment state, Provider status, 3-D Secure status, Actual currency and Actual amount (minor units), Expected currency and Expected amount (minor units), Merchant Account ID, the link Open transaction in Braintree Control Panel of the payment's environment, and the list of operations sent to Braintree. The information stays available after the settings and keys are deleted. The customer sees only the payment method title.

Capture and void

For an order with Authorize only, click Invoice, choose Capture Online and submit the invoice to charge the reserved amount. Only the full authorized amount can be captured; the order total must not change after the payment. To release the funds, click Void or Cancel on the order page. If Braintree does not accept the action, Magento shows the error and the invoice or the cancellation is not saved.

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 money is sent back through Braintree. Full and partial refunds are supported, up to the amount Braintree charged minus the amounts already refunded. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Braintree.

Braintree refunds only settled transactions, usually within 24 hours. Before settlement a refund of the full amount is done as a void; a partial refund fails with Braintree partial refunds require settlement. Refund the full original amount to void it now, or retry the partial refund after settlement. The refund is sent to the environment (sandbox or live) and merchant of the payment, so the credentials of that environment must be set. If Braintree does not accept the refund, Magento shows the error and the credit memo is not created. A full refund closes the order. Disputes (chargebacks), settlement declines and refunds made in the Braintree Control Panel are not synced to Magento; record them with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Braintree Gateway is the first row of the VibeFox Braintree 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-braintree 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, Braintree is not shown to customers at checkout and the card form is not loaded. If a payment is started anyway, no card is charged, the order stays in Pending Payment and the customer sees This payment method is not available. Please choose another one. Back to cart cancels the order and restores the cart. 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: captures, voids and refunds work, and a charged payment can still be completed.

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

Braintree does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the selected environment has a Merchant ID, Public Key and Private Key: the sandbox fields with Sandbox Mode = Yes, the live fields with No. The Braintree Setup row shows a warning when a key is missing. 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 card was charged, but the order stays Pending Payment: card payments are confirmed immediately, without a webhook. Look at the Log field in the Advanced section and at the Braintree payment information of the order. If the answer from Braintree was lost, find the transaction with the cart number as the order ID in the Braintree Control Panel before accepting another payment. If the card was charged but the order could not be completed, the customer can complete it on the payment page with Complete order, without a new charge.

The card form shows Could not initialize the Braintree form. Refresh and try again.: the keys of the selected environment are wrong, or the merchant account ID does not exist in that account. Check the keys and the merchant account ID(s), then reload the page.

3-D Secure fails for every payment: 3-D Secure must be enabled for your Braintree merchant account. Contact Braintree support, or set 3-D Secure to Disabled (not recommended in the EEA and UK, where SCA is mandatory).

The customer is told that the amount or currency did not match: Braintree charged in the currency of the merchant account. Enter the merchant account ID for the order currency in the merchant account field of the current environment.

The customer sees The order total must be greater than zero.: the order total is zero, for example after a discount. Such orders cannot be paid by card.

The customer sees The order total or payment environment changed. Refresh the Braintree form.: the cart total, the currency or Sandbox Mode changed after the card form was loaded, or the form is older than 30 minutes. The customer enters the card again.

A partial refund fails right after the payment: Braintree can only refund settled transactions, usually within 24 hours. Refund the full amount to void the transaction now, or make the partial refund after settlement.

Capture, void or refund fails with The Braintree credentials of the original payment environment are missing.: the payment was made in the sandbox or live environment, and the credentials of that environment are not set, or its Merchant ID was changed. Enter the credentials of the account the order was paid with and try again.

An operation fails with a message about an uncertain result or reconciliation: an earlier request to Braintree got no clear answer. No second request is sent until you check the transaction in the Braintree Control Panel. Turn on Debug Log to see the details.

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 an uncaptured authorization or an order On Hold) cannot be refunded online.

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

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

The license key and license status are always removed. If Delete Data on Uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Braintree transactions and operations are always kept, so orders paid before can still be captured, voided or refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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