Woo Braintree Payment FAQ

    Q : While on Admin I’ve got the message shown below. What does it mean?

    Braintree Payment Gateway is enabled, but the force SSL option is disabled; your checkout may not be secure! Please enable SSL and ensure your server has a valid SSL certificate

    A : The plug-in checks if the WooCommerce > Checkout > Force secure checkout option is set or if you use HTTPS (instead HTTP) while using the Admin dashboard. If any of these two pre-conditions are not met it throws the message mentioned above.

    Q : The plug-in is Enabled but the payment method does not appear on the checkout page. Why?

    A : This may happen in any of the following cases:

    • the plug-ins Enable this payment gateway option is off
    • the plug-in is in Production mode (ie. Enable Sandbox mode is off) AND WooCommerce > Checkout > Force secure checkout option is set AND you are using HTTP instead HTTPs while on Checkout page. This situation should never happen, though.
    • either the Braintree Merchant Id, the Public or the Private key are not set

    Q : The payment methods box in the checkout page has a foggy layer on top. Cannot click any field of it except the Billing Details fields. Why?

    A : Obviously something is blocking the payment methods box. The cause could be any of the active payment methods. Try to disable one by one any of your active payment methods and see which one blocks that box. If it seems to be our plug-in (ie. Braintree payment method) then check your browser console for any JavaScript error message (see How to open your browser console). If there is no message then try to clear your browser’s cache/cookies. If you found a message try to see if it contains any valuable information that may help you fix the cause. In any of these cases please report this issue.

    Q : Using the Custom UI integration on a mobile device (eg. Android) only the CCV field triggers the numeric keypad activation. Why not also for card number or expiry fields as well?

    A : This is due to WooCommerce default card form which implements all fields (including CCV) as type=”text”. The reason for this is that some fields (especially card number and expiry) has a special pattern like ****[space]****[space]****[space]**** or MM[space]/[space]YY which would require a text field type. Obviously we could override this behaviour but in order to make sure the plug-in is 100% WooCommerce compatible we chose not to do so. However, due the fact that the CCV field has no particular format/pattern behind it we chose to make a compromise and override at least this field type (as number).

    Q : When using Custom UI integration by clicking the “Place order” button on the checkout page it will shake the card number field as it contains invalid card number, but it doesn’t. Why?

    A : If you are using the PRO version then probably, while testing, you changed the UI integration type option to something else than Custom UI then reverted back. Somehow the “Cards regex pattern” option is now empty which means no rule to validate the card number. Just go to the Custom UI tab in the Braintree Payment Setting page and click the button “Reset to default” (within Cards regex pattern option) to insert the factory default card regex patterns. Starting with v0.1-16 when there is no regex rule defined then the factory default rules are used by default.

    Q : By using a PayPal button or a non CustomUI integration (eg. Drop-in UI, Hosted Fields UI) I saw that, while on checkout page, if I have selected the (Braintree) card payment method then I change some address field the PayPal button ‘disappear’ or in case of Drop-in/Hosted Fields UI the whole card form UI ‘disappear’. What is happening?

    A : This is due to a WooCommerce design which transparently post each keystroke/change to the server then reinitializes the whole thing based on the previously saved data, which is fine. The only problem is that the Braintree elements (such as a PayPal button, a Drop-in UI or Hosted Fields UI) do not belongs to the WooCommerce default card form. The server doesn’t know about them, they are created at runtime via JavaScript only at the client’s browser level. So by rendering the whole page will result in creating all elements except Braintree runtime one.

    For Drop-in/Hosted Fields UI we have found an workaround: when this is happening we intentionally select the first payment method (like Direct Bank Transfer) that is not (1) Braintree and (2) already selected. By doing that we force the buyer to select again its preferred payment method as soon as he/she is finishing editing the checkout form. A general workaround is to manually select another payment method and then select back this payment method.

    Please note this is only a workaround until we find a way to cope with WooCommerce. Obviously we can override the WooCommerce behaviour but probably this is not the right way of doing it so until we find a safe method we go like this 🙁

    Tips: You may use the Custom UI integration which does not suffer of this syndrome. As with v0.2-22 there is an Prevent Checkout updates option.

    Q : The Braintree card payment is selected. While filling the checkout form it seems that this payment method is unselected and some other method becomes automatically selected instead. Why?

    A : This is true. In fact this was created intentionally. Please check the previous question to find out “why”.

    Q : The payment gateway is not working. When clicking the Test connection button I got the following message:

    Oops!… The payment gateway is not available

    A : This might happen when the plug-in noticed that the Braintree gateway is not available. There are many reasons for this. The most common are:

    • invalid Braintree merchant Id and/or the public/private keys (make sure you use the Production keys on Production mode and Sandbox keys on Sandbox mode and not vice-versa)
    • the plug-in is set on Production mode AND you are not using SSL AND Force Secure Checkout is set on the WooCommerce Checkout Options page (check also this)

    Q : Payment is not processed but an error message like the one below is thrown:

    The following request received without payment_method_nonce field. This should never happen! Try to clear your browser’s cache and see if that helps. This should never happen!

    Why is that and how to fix it?

    A : The authentication process with the Braintree Payment Gateway is done via a Secure Socket Layer (SSL) by using a secure client token. Using this token the client info (ie. card number. expire date, CCV) is encapsulated within a data blob and sent by the client browser to the Braintree Payment Gateway (your webshop server never touches these sensitive info, it’s a communication between end-user and Braintree gateway). As result the Payment Gateway will response with a cryptographic payment_method_nonce which is just a reference to the real payment information (card info) that was earlier sent by your client to the Braintree.

    When your customer clicks the “Place Order” button within the Checkout page the plug-in sends, besides the order amount and other order details, that payment_method_nonce field. Without this payment_method_nonce field the Braintree Payment Gateway doesn’t know what card your customer are using for the current payment. Read how it works.

    The request for the payment_method_nonce field is done by using a JavaScript Client SDK library developed and provided by Braintree. The only logical reason for that field to not exist is when the JavaScript call either does not take place or generates an error on client’s browser. In order to debug what is going on please check that:

    1. there is no JavaScript error shown on the browser’s Console
    2. the following JavaScripts scripts are loaded within the client browser:
      • woo-mynix-braintree-gateway-VER.js
      • woo-mynix-braintree-gateway-VERUITYPE.js where VER can be empty or pro and UITYPE can be one of custom, paypal or hosted

    If for any reason (1) does not verify then check to see the source of the JavaScript errors. There might be other WordPress plug-ins and/or themes with broken code which might trigger these errors and thus might break the normal execution flow.

    If for any reason (2) does not verify it means that one|all of the plug-in scripts is|are not loaded and|or executed and therefore Request received without payment_method_nonce field error message. This might happen if you are using a CDN caching provider (like CloudFlare CDN) or some other caching plug-in. If that’s the case then try to disable the caching provider|plug-in for the Checkout page URL (or entirely) then check if that does the trick.

    Q : When I choose the (Braintree) card payment method the checkout form throws an error message like the one below:

    The order does not support PayPal button payment method.

    Why is that and how to fix it?

    A : The short answer is that the merchant’s Braintree account does not support the payment method’s currency of the current order. If that happens you should contact the webshop merchant.

    The long answer (rather for the webshop merchant than for its customer) should start by saying that the above situation may only happen in relation with an Sandbox account, the PayPal button enabled and, eventually, some additional merchant IDs defined.

    First, make sure that the order currency is within the PayPal supported currencies. If the order currency is not supported then perhaps you should disable the the PayPal button or change your shop working currency. However, in the PRO version you may choose the PayPal conversion option which will convert transparently the order amount to a Braintree-Paypal supported currency. That way your webshop customer might be able to use the PayPal button payment method even with a PayPal not-supported currency.

    Sometimes it happens that, originally, when your Sandbox was created, there was only your default merchant account around so the automated setup of the Sandbox naturally setup PayPal for that merchant account (also the default one, like USD). This means that unless you use the one or any other that is setup to accept your currency via PayPal you are likely to see that error.

    The solution is to contact the Braintree Support and to explain them the following:

    you are trying to make a payment on your Sandbox account via PayPal button using a X currency AND the Braintree Merchant Account named Y but the plugin that is sending the API call to the Braintree server returns a generic error message like the payment method is not supported which the plugin got it while it initializes the Braintree client JavaScript SDK.

    They will trace the payment call that was rejected and will tell you exactly the thing I explained above. Nonetheless they might even setup the Sandbox account for you such that you may test those kind of payments.

    Please note that this error should normally never happen in Production (where you have full-access), unless you have not configured well the PayPal and the additional merchant IDs.

    To make sure the above is true then here is what you can do:

    1. check that your Production account is setup well
    2. switch the plugin into Production mode
    3. go to your Checkout page: does the error still appear?

    Q : I am testing the PayPal button on Sandbox. When I click the button it opens a small window and shows the following message:

    Sorry we cannot connect to PayPal. Please try again in a few minutes. Try Again.

    What does it mean and how to fix this?

    A : The short answer is that there is a problem with your Braintree account setup.

    The long answer is that, probably, your Braintree Sandbox account is not setup to accept payments for any other currency than US Dollar. So, for instance, if your order amount is given in SEK (Swedish Krona) and your Sandbox account is configured to accept only PayPal USD then you will get that message instead of a PayPal login screen or alike.

    What you should do is to contact the Braintree Support and to explain them exactly the situation (you are testing your Sandbox with PayPal for whatever currency and you get that message). They will certainly help you by correcting your Braintree Sandbox settings, which will allow you to test the PayPal with the respective currency.

    If you want to test the PayPal button without having to wait for their reply then just change TEMPORARILY your webshop currency to USD and it should work like a charm (your Sandbox is PayPal USD enabled by default).

    Please note that this situation might even appear while working on the Production environment, if the circumstances are exactly the same.

    Q : How does the Braintree’s Recurring billing work with this plug-in?

    A : With Braintree’s recurring billing, you can charge your customers automatically in monthly increments.

    To make this possible we have to inter-connect three different ends:

    1. the WooCommerce web shop, which is the front door for the entire thing
    2. the Braintree, which will bill the payer on behalf you
    3. the plug-in, which acts as a bridge between the WooCommerce and Braintree

    Setup your system – Step By Step

    1. In the WooCommerce web shop you must define a product/service the customers may buy and pay in monthly increments (like a subscription, the monthly payments you do for your car, house, etc). Let’s note that product SKU with X, ie. `SKU=X`
    2. In the Braintree dashboard -> Recurring Billing -> Plans add a `New` billing plan which will be the Braintree’s equivalent of your WooCommerce SKU=X product. Here it is called Billing Plan and have many options that let you define how the recurrent payment has to be made.
    3. when the both steps above are done, go in the plug-in Settings -> Recurring then map a (WooCommerce) SKU to a (Braintree) billing plan. You will be able to choose from your defined Braintree’s billing plans then you enter manually the WooCommerce SKU that matches the specified billing plan. This is what I call a “mapping”, thus `Map a SKU to a recurrent plan ID` option.
    Repeat the three steps above for each product/service that the customer may purchase and pay to you it in incremental/recurrent payments.

    How it works

    1. The customer buys a recurrent billing product/service from your website and proceeds with the payment in the Checkout page
    2. our payment plug-in finds what order items has a mapping defined as on step 3 above
    3. for each such item it does the following (using the product SKU – billing plan ID mapping):
      • adds the new customer (with its address, payment method details, etc) into the Braintree Vault
      • creates a Braintree subscription for that customer and the given product (ie. billing plan)
    4. the order is done! – the Braintree will charge the customer periodically (using its Vault stored payment method), at the interval defined per Recurring Billing Plan

    Q : By using the PayPal button where I specify a shipping address and confirm the payment the checkout form requires me to re-authenticate by showing the following message:

    The order shipping address was updated using the PayPal specified shipping address. This might require you to re-authenticate to your PayPal account.


    A : The eCommerce plugin (WooCommerce) used by the website recreates automatically some parts of the checkout form every time the billing|shipping address is updated. When this happens it recreates also the container where the PayPal button is placed.

    However, when you are re-authenticating you would normally specify the same address again. Obviously by using again the same address there would be no further shipping address changes, therefore no re-authentication would be required.
    It sucks, I know 🙁 . Unfortunately there is nothing we can do about it.

    Q : The Checkout page shows the following error message:

    Payment cannot be processed. Order currency (`XXX`) is not available for the selected payment method (`YYY`). This is rather a merchant plugin miss-configuration (`N`).

    What should I do?

    A : This message suggests that a website plugin miss-configuration was detected. Normally this should be reported to the website merchant (which normally it’s done automatically) and nonetheless refrain from using the Card payment method until it gets fixed.

    In this message the `XXX` and respectively `YYY` may indicate a currency code (eg. USD) and the `N` represents a numerical error code, as following:

    • (1) this code indicates that the `XXX` currency is not supported by the payment gateway
      • if that’s true then the merchant should either configure its eCommerce webshop to a payment gateway supported currency or it can use a currency converter plugin
      • In case of a PayPal payment method it could enabled the plugin’s `PayPal amount conversion` option.
    • (2) this code indicates that the order currency `XXX` is different than the `YYY` currency of the merchant account chosen for that payment
      • in this case the merchant should either set its eCommerce webshop currency to `YYY` or setup an additional Braintree merchant account that supports its `XXX` webshop currency

    Q : The Drop-in UI doesn’t show the PayPal button although I have enabled the PayPal option and also my Braintree setup enables PayPal. What could be the cause?

    A : If you are using the FREE version of the plug-in then make sure that the Braintree merchant ID you have chosen supports PayPal (check your Braintree setup).
    If you are using the PRO version of the plugin then check the following:

    • check the WooCommerce currency for your webshop (let’s note that with `A`)
    • check the plugin setting (`Enhanced` tab) for the `Additional Merchant IDs`. Is there any merchant account which currency would match the `A` noted above?
      • if YES then make sure that that additional merchant account ID supports PayPal (check within your Braintree setup)
      • if NO then the only logical explanation is that your Braintree setup does not enabled PayPal

    Q : When placing an order, although the `Ignore 3D-Secure if AVS` option is ON, I still get the

    Your card is not 3D-Secure eligible. Please use a 3D-Secure enrolled card or choose other payment method.

    error message. Why?

    A : There are two different scenarios:

    1. the `Allow only 3D-Secure cards` option is ON
      • If the card is eligible for 3D-Secure authentication but the user fails the authentication for whatever reason, by using the `Ignore 3D-Secure if AVS` option we will relay on the AVS rules. If the AVS rules match then, despite of the previous 3DS failure, the transaction would succeed.
      • However, if the card is not eligible for 3D-Secure authentication then the `Ignore 3D-Secure if AVS` option is ignored completely. That’s because the system is set to `Allow only 3D-Secure cards`.
    2. the `Allow only 3D-Secure cards` option is OFF
      • The above error message should never be thrown in this case. Instead, a different error message should be provided, one which should also specify the exact cause of error.

    Q : The PRO version has an option called `Developer Mode`.
    What it is good for?

    A : The developer mode option activates some features that allows one to stress the plug-in in order to understand how it responds under various circumstances. Basically it allows to:

    Note: this option works only while on Sandbox-Mode.
    However, you may always test (with/without this option) how the plugin and/or the payment gateway respond while using some test card numbers, test CVV codes, billing postal codes and street addresses. This is something independent of the plugin itself, it’s rather a matter of specifying some special numbers/codes that, while on Sandbox-mode, the payment gateway will treat specially.

    Q : On the `Checkout` options group I saw an option called `Prevent Checkout updates`. How does it work?

    A : While editing the Billing|Shipping addresses on the checkout page the WooCommerce will reload some fragments of the checkout page, for instance the payment form. This means that the payment form will be destroyed together with everything it contains, including our payment plugin. See question #6 for more details.

    In order to address that, starting with v0.2-22 we introduced a new option, the `Prevent Checkout updates` option. It basically tells the WooCommerce not to refresh some fragments after each key stroke. That’s all it takes. So, while using this option, by changing the billing Country, the State or Postal Code the payment form won’t refresh after each keystroke. However, if you choose some other payment option (like BACS, CASH, etc) or if you would deselect this option, the WooCommerce will work as designed.