How we solved Braintree & Magento 2 checkout issues with our Magento 2.1 store

Summary

After investigation, we found three independent causes behind Braintree checkout failures on Magento 2.1. Applying the solutions below reduced declines significantly; we stopped receiving reports of failed checkouts.

Issue

Some customers saw: “An error occurred on the server. Please try to place the order again.”

Root causes varied (address/region validation, payment method mismatch, and bank soft declines).

Solution 1 — Missing region at checkout

Countries without preset regions (e.g., the UK) may fail validation if a region is not present.

Fix: install a small workaround module: https://github.com/gloong/module-quote

(Reported Magento core issue example: https://github.com/magento/magento2/issues/7387)

Solution 2 — Payment method mismatch (Magento vs. Braintree)

If accepted card types differ between Magento Braintree settings and your Braintree Merchant Account, checkout can error.

Example: AMEX enabled in Magento but not enabled in Braintree.

Fix: make sure both sides match.

• Magento Admin: Configuration → Sales → Payment Methods → Braintree → Advanced settings → Credit Card Types

• Braintree: Settings → Processing → Merchant accounts

Solution 3 — Bank restrictions (soft declines) + clearer messaging

After applying Solutions 1 & 2, remaining errors stemmed from bank declines (limits reached, unusual activity, insufficient funds, address/ZIP mismatch, etc.). Showing a generic server error confused customers.

Action: replace the message with a clearer soft decline notice that guides customers to contact their bank.

• Old: An error occurred on the server. Please try to place the order again.
• New: Your bank is unwilling to accept the transaction. This is a soft decline. Please contact your bank and try again.

How to implement Solution 3 (SQL translation override)

Add storefront-specific translations to the translation table. Use straight quotes and your store’s store_id and locale.

• Insert (message variant 1):

INSERT INTO translation (string, store_id, translate, locale) VALUES ('An error occurred on the server. Please try to place the order again.', 1, 'Your bank is unwilling to accept the transaction. This is a soft decline. Please contact your bank and try again.', 'en_US');

• Insert (message variant 2):

INSERT INTO translation (string, store_id, translate, locale) VALUES ('A server error stopped your order from being placed. Please try to place your order again.', 1, 'Your bank is unwilling to accept the transaction. This is a soft decline. Please contact your bank and try again.', 'en_US');

Notes:

• Replace 1 with your store_id.
• Replace en_US with your locale (e.g., en_GB, de_DE).
• Clear caches after changes if needed.

Conclusion

• Fix the region requirement for countries without preset regions.
• Align accepted card types between Magento and Braintree.
• Clarify soft declines with a helpful message so customers know to contact their bank.

These steps eliminated Braintree checkout errors in our Magento 2.1 setup.

Updated on: 16/09/2025