Braintree

Braintree offers a fully customizable checkout experience with fraud detection and PayPal integration. It supports Apple Pay, Google Pay, ACH, Venmo, and local payment methods. Braintree reduces the PCI compliance burden for merchants because the transaction takes place on the Braintree system. The Braintree Payments integration is developed by GENE Commerce.

Step 1: Get your Braintree credentials

Go to Braintree Payments and sign up for an account.

Step 2: Complete the basic settings

1. On the Admin sidebar, go to Stores > Settings > Configuration.

2. In the left panel, expand Sales and choose Payment Methods.

   • If your Commerce installation has multiple websites, stores or views, in the upper-left corner, choose the Store View where the configuration applies.

   • In the Merchant Location section, verify that Merchant Country is set to the location of your business.

3. Under Recommended Solutions, in the Braintree Payments (by GENE Commerce) v4.5.0) section, click Configure.

   

4. For Title, enter a title that identifies Braintree as a payment option during checkout.

5. Set the current operating Environment for Braintree transactions to Sandbox or Production

   When testing the configuration in a sandbox, use only credit card numbers that are recommended by Braintree. When you are ready to go to production with Braintree, set Environment to Production.

   

6. Set Payment Action to one of the following:

   • Authorize Only - Approves the purchase and puts a hold on the funds. The amount is not withdrawn from the customer’s bank account until the sale is captured by the merchant.|
   • Intent Sale - The amount of the purchase is authorized and immediately withdrawn from the customer’s account. Note: This value was Authorize and Capture in 2.3.x and earlier releases.|

7. Enter the Sandbox Merchant ID / Merchant ID from your Braintree account.

8. Enter the following credentials from your Braintree account:

   • Sandbox Public Key / Public Key
   • Sandbox Private Key / Private Key
   NOTE

   There are separate fields for both (Sandbox and Production) environments, and the other fields render based on which environment is selected.

9. Before saving the configuration, click Validate Credentials to validate your credentials.

10. Set Enable Card Payments to Yes.

    

    If you want the ability to store customer information securely, so customers don’t have to reenter it each time they make a purchase, set Enable Vault for Card Payments to Yes.

Step 3: Complete the advanced settings

1. Expand the Advanced Braintree Settings section.

   

2. For Vault Title, enter a descriptive title for your reference that identifies the vault where your customer card information is stored.

3. Enter the Merchant Account ID from your Braintree account.

   If you don’t specify the merchant account to be used, Braintree processes the transaction using your default merchant account.

4. If you want to prevent the transaction from being sent for evaluation as part of Advanced Fraud Tools checks, on orders placed through the Admin, set Skip Fraud Checks on Admin Orders to Yes.

5. Set the Bypass Fraud Protection Threshold so that the Advanced Fraud Protection checks are bypassed when the threshold is met or exceeded.

   Leaving this field blank disables this option.

6. If you want the system to save a log file of interactions between your store and Braintree, set Debug to Yes.

7. To require customers to provide the three-digit security code from the back of a credit card, set CVV Verification to Yes.

   If using CVV verification, make sure to enable AVS and/or CVV in the Settings/Processing section of your Braintree account.

8. To send the cart line items for all the payment methods, set Send Card Line Items to Yes.

9. For Credit Card Types, select each credit card that is accepted by your store as payment through Braintree.

   To select multiple card types, hold down the Ctrl key (PC) or the Command key (Mac) and click each option.

10. For Sort Order, enter a number to determine the sequence in which Braintree appears when listed with other payment methods during checkout.

Step 4: Complete the Braintree webhooks settings

1. Set Enable Webhook to Yes to enable the webhook functionality for fraud protection, ACH payments, and local payment methods.

2. Copy the URL in the Fraud Protection URL field and add it to your Braintree account as the Webhook Destination URL.

   IMPORTANT

   This URL must be secure and publicly accessible.

3. Set the Fraud Protection Approve Order Status field to determine when fraud protection is approved by Braintree.

   The selected order status is assigned to the Commerce order.

4. Set the Fraud Protection Reject Order Status field to determine when fraud protection is rejected by Braintree.

   The selected order status is assigned to the Commerce order.

Step 5: Complete the country-specific settings

1. Set Payment from Applicable Countries to one of the following:

   • All Allowed Countries - Customers from all countries specified in your store configuration can use this payment method.
   • Specific Countries - After choosing this option, the Payment from Specific Countries list appears. Hold down the Ctrl key (PC) or the Command key (Mac) and select each country in the list where customers can make purchases from your store.
   

2. To set up Country Specific Credit Card Types:

   • Click Add.

   • Set the Country and choose each Allowed Credit Card Type.

   • Repeat to identify the credit cards that are accepted from each country.

Step 6: Complete the ACH through Braintree settings

1. To include ACH as a payment option with Braintree, set Enable ACH Direct Debit to Yes.

2. For Sort Order, enter a number to determine the sequence in which the Braintree ACH payment option appears when listed with other payment options during the checkout.

Step 7: Complete the Apple Pay through Braintree settings

1. To include Apple Pay as a payment option with Braintree, set Enable ApplePay through Braintree to Yes.

   Make sure to verify your domain name in your Braintree account first.

2. Set Payment Action to one of the following:

   • Authorize Only - Approves the purchase and puts a hold on the funds. The amount is not withdrawn from the customer’s bank account until the sale is captured by the merchant.
   • Intent Sale - The amount of the purchase is authorized and immediately withdrawn from the customer’s account.

3. For Merchant Name, enter text that specifies the label that is displayed to customers in the Apple Pay dialog.

4. For Sort Order, enter a number to determine the sequence in which Apple Pay payment option appears when listed with other payment options during the checkout.

Step 8: Complete the local payment methods settings

1. To include local payment methods as a payment option with Braintree, set Enable Local Payment Methods to Yes.

2. For Title, enter the text to use for the label that appears on the checkout payment method section (default value: Local Payments).

3. For Allowed Payment Methods, select the local payment method to be enabled.

   Options: Bancontact / EPS / giropay / iDeal / Klarna Pay Now / SOFORT / MyBank / P24 / SEPA/ELV Direct Debit

   

4. For Sort Order, enter a number to determine the sequence in which local payment method appears when listed with other payment options during the checkout.

Step 9: Complete the Google Pay through Braintree settings

1. To include Google Pay as a payment option with Braintree, set Enable GooglePay Through Braintree to Yes.

2. Set Payment Action to one of the following:

   • Authorize Only - Approves the purchase and puts a hold on the funds. The amount is not withdrawn from the customer’s bank account until the sale is captured by the merchant.
   • Intent Sale - The amount of the purchase is authorized and immediately withdrawn from the customer’s account.

3. Set Button Color to determine the color of the Google Pay button: White or Black

4. For Merchant ID, enter your MerchantID (provided by Google).

5. For Accepted Cards, select the type of cards that a customer can use to place order using Google Pay.

   Options: Visa / MasterCard / AMEX / Discover / JCB

6. For Sort Order, enter a number to determine the sequence in which Google Pay appears when listed with other payment options during the checkout.

Step 10: Complete the Venmo through Braintree settings

1. To include Venmo as a payment option with Braintree, set Enable Venmo through Braintree to Yes.

   

2. Set Payment Action to one of the following:

   • Authorize Only - Approves the purchase and puts a hold on the funds. The amount is not withdrawn from the customer’s bank account until the sale is captured by the merchant.
   • Intent Sale - The amount of the purchase is authorized and immediately withdrawn from the customer’s account.

3. For Sort Order, enter a number to determine the sequence in which Venmo appears when listed with other payment options during the checkout.

Step 11: Complete the PayPal through Braintree settings

1. To include PayPal as a payment option with Braintree, set Enable PayPal through Braintree to Yes.

2. Specify your PayPal through Braintree payment method:

   NOTE

   Either PayPal Credit or PayPal PayLater can be enabled. Both the methods cannot be enabled at the same.

   • To include PayPal Credit as a payment option with Braintree, set Enable PayPal Credit through Braintree to Yes.

     When Enable PayPal through Braintree is set to Yes, only this field appears.

     NOTE

     PayPal Credit is only available in the United States and United Kingdom. PayPal Credit is disabled if the selected value for the Merchant Country field is not US or UK.

   • To include PayPal PayLater as a payment option with Braintree, set Enable PayPal PayLater through Braintree to Yes.

     When Enable PayPal PayLater through Braintree is set to Yes, only this field appears.

     You can display PayLater messaging on your site for offers, such as Pay in 3, which lets customers pay with three interest-free monthly payments. The Braintree integration can display messages on your site to promote this feature. You cannot promote PayLater offers with any other content, marketing, or materials.

3. For Title, enter a title that identifies the Braintree payment by PayPal option during checkout.

4. Set Vault Title to Yes to enable use of a secure vault to store customers’ credit card information.

5. For Sort Order, enter a number to determine the sequence in which the Braintree PayPal payment option appears when listed with other payment options during checkout.

6. To display your merchant name differently than what is defined in your store configuration, enter the name in the Override Merchant Name field as you want it to appear.

7. Set Payment Action to one of the following:

   • Authorize Only - Approves the purchase and puts a hold on the funds. The amount is not withdrawn from the customer’s bank account until the sale is captured by the merchant.
   • Authorize and Capture - The amount of the purchase is authorized and immediately withdrawn from the customer’s account.

8. Set Payment from Applicable Countries to one of the following for Braintree transactions processed by PayPal:

   • All Allowed Countries - Customers from all countries specified in your store configuration can use this payment method.
   • Specific Countries - After choosing this option, the Payment from Specific Countries list appears. Hold down the Ctrl key (PC) or the Command key (Mac) and select each country in the list where customers can make purchases from your store.

9. To require customers to provide a billing address, set Require Customer’s Billing Address to Yes.

   NOTE

   This feature must be enabled for your account by PayPal Technical Support.

10. To save a log file of interactions between your store and PayPal through Braintree, set Debug to Yes.

11. To display the PayPal button on both the mini cart and shopping cart page, set Display on Shopping Cart to Yes.

Step 12: Set the styling settings

1. For Location, choose where PayPal buttons and messages are rendered: Mini-Cart and Cart Page, Checkout Page, or Product Page

   

Mini-Cart and Cart Page

The option and settings in this section vary according to the setting in the Location field.

1. Set PayPal Button Type to one of three types of buttons: PayPal Button / PayPal Pay Later Button / PayPal Credit Button

PayPal Button

The options and settings in this section vary according to the button type selected in the PayPal Button Type field.

1. To show the PayPal button on the storefront at the selected location, set Show PayPal Button to Yes.

2. For Button Label, select the PayPal button label: Paypal, Checkout, Buynow, or Pay

3. For Color, select the PayPal button color: Blue, Black, Gold, or Silver

4. For Shape, select the PayPal button shape: Pill or Rectangle

5. For Size, select the PayPal button size: Medium, Large, or Responsive

PayLater Messaging

1. To show PayLater messaging on the storefront at the selected location, set Show PayLater Messaging to Yes.

   This messaging includes the display of PayLater messaging for available offers (restrictions apply).

2. For Message Layout, select the PayLater message layout: Text or Flex

3. For Logo, select the PayPal logo type: Inline, Primary, Alternative, or None

4. For Logo Position, select the PayPal logo position: Left, Right, or Top

5. For Text Color, select the PayLater message text color: Black, White, Monochrome, or Grayscale

When these options are set, you can see the preview of the PayPal buttons and PayLater messages. There are controls that you can use to apply the settings or reset the values:

• Click Apply to store the selected styling settings for buttons and PayLater messaging and apply them to the current location and current button type.

• Click Apply to All Buttons to store the selected styling settings for buttons and PayLater messaging values and apply them to all button types and locations.

• Click Reset to Recommended Defaults to return styling settings to the recommended default values for buttons and PayLater messaging and apply them to all button types and locations.

Step 13: Complete the 3D verification settings

1. If you want to add a verification step for customers using credit cards that are enrolled in a verification program (such as Verified by VISA), set 3D Secure Verification to Yes.

   During the process, the transaction amount that is submitted for verification is checked against the amount that is sent for authorization.

2. To always challenge the 3D Secure request for all transactions, set Always request 3DS to Yes.

3. For Threshold Amount, enter the minimum order amount that is required to trigger 3D verification.

4. Set Verify for Applicable Countries to one of the following:

   • All Allowed Countries - Customers from all countries specified in your store configuration can use this payment method.
   • Specific Countries - After choosing this option, the Verify for Specific Countries list appears. Hold down the Ctrl key (PC) or the Command key (Mac) and select each country in the list where customers can make purchases from your store.
   

Step 14: Set up the Braintree dynamic descriptors

The following descriptors are used to identify purchases on customer credit card statements. You can reduce the number of charge backs by clearly identifying the company that is associated with each purchase. If dynamic descriptors are not enabled for your account, contact Braintree support.

1. Enter the dynamic descriptor for the Name, Phone, and URL according to these guidelines:

   • Name - There are two parts to the name descriptor, which are separated by an asterisk (*). For example:

     company*myproduct

     The first part of the descriptor identifies the company or DBA, and the second part identifies the product. The length of the company and product parts of the descriptor can be allocated in the following ways, for a combined length of up to 22 characters.

     Characters in name descriptor

     Option 1: Company must be three characters, Product may be up to 18 characters

     Option 2: Company must be seven characters, Product may be up to 14 characters

     Option 3: Company must be 12 characters, Product may be up to nine characters

   • Phone - The phone descriptor must be 10 – 14 characters in length, and can include only numbers, dashes, parentheses, and periods. For example:

     9999999999

     (999) 999-9999

     999.999.9999

   • URL - The URL descriptor represents your domain name, and can be up to 13 characters long. For example:

     company.com

2. When your Braintree configuration is complete, click Save Config.

2.4 upgrade notes

Before upgrading to Commerce 2.4 from 2.3, it is recommended that merchants replace the core Commerce Braintree integration with the official Braintree extension from Commerce Marketplace. Beginning with Adobe Commerce and Magento Open Source 2.4.0, the Braintree extension is included in the release.

If you are migrating to Commerce 2.4.x from a pre-2.4.0 version that has the Marketplace Braintree extension installed, you must uninstall that extension (paypal/module-braintree or gene/module-braintree) and update any code customizations to use the PayPal_Braintree namespace instead of Magento_Braintree. Configuration settings from the core Commerce Braintree Payments bundled extension and the extension distributed on Commerce Marketplace persist and payments placed with those previous versions can still be captured, voided, or refunded as normal.

Business.Adobe.com resources