Braintree Payment Gateway

RestroPress Braintree Payment Gateway adds Braintree card payments to your checkout. Customers type their card details into secure Braintree Hosted Fields on your own checkout page, and the order is charged straight away. It can also ask for 3D Secure verification and let logged-in customers save a card for later orders. It is for restaurants that have a Braintree merchant account.

Requirements#

• RestroPress, active. The gateway starts only when RestroPress is loaded; no minimum version is checked.
• A Braintree account (sandbox for testing, production for live orders) with a Merchant ID, Public Key and Private Key. A Tokenization Key is needed unless you use 3D Secure.
• HTTPS on your site. The plugin bundles the Braintree PHP SDK (version 6.28.0) and loads the Braintree web SDK 3.139.0 from js.braintreegateway.com.

Installation#

1. In WordPress go to Plugins › Add New › Upload Plugin, choose the ZIP file and install it.
2. Activate RestroPress Braintree Payment Gateway.
3. Open RestroPress › Settings › Payment Gateways › Braintree and fill in the settings below.
4. Go to the General section of the same tab, tick Braintree in the list of gateways, and save.

The plugin has no licence key field, so there is nothing to enter under RestroPress › Settings › Licenses for it.

Provider account steps#

1. In the Braintree Control Panel, open Settings › API and copy the Merchant ID, Public Key and Private Key. Do this separately in the sandbox and the production control panels; they have different keys.
2. Create a Tokenization Key in the same area (needed for the card form when 3D Secure is off).
3. Optionally note a Merchant Account ID if you have more than one merchant account or currency.
4. Add a webhook destination in the Control Panel using the Webhook URL shown on the Braintree settings screen, then use Test Braintree Webhook Challenge in the plugin to check the keys. The URL has the form https://your-site.com/wp-json/rpress-braintree/v1/webhook. A legacy URL https://your-site.com/index.php?rpress-listener=braintree also works.

Settings#

Found under RestroPress › Settings › Payment Gateways › Braintree, below the heading Braintree Settings, which also shows the web SDK and bundled PHP SDK versions.

Setting	What it does	Default
Merchant ID	Your Braintree Merchant ID. Required.	Empty
Merchant Account ID	Optional. A specific Braintree merchant account to use for charges and client tokens.	Empty
Public Key	Your Braintree Public Key. Required; also used to sign the webhook challenge.	Empty
Private Key	Your Braintree Private Key. Required. Entered in a password field.	Empty
Tokenization Key	Used by the secure card form. Required unless 3D Secure is on.	Empty
3D Secure	"Verify eligible cards with Braintree 3D Secure before submitting the order." With this on, the card form is started with a client token generated from your API keys instead of the Tokenization Key.	Off
Require 3D Secure liability shift	Rejects the checkout when 3D Secure says liability shift is not possible or did not happen.	Off
Saved Cards	Lets logged-in customers save a card for repeat orders. Customers must opt in at checkout.	Off
Webhook URL	Information only: the URLs to add in Braintree.	-
Test Connection	A Test Braintree Webhook Challenge button. It only checks that the public and private keys are present and that a webhook challenge response can be built; it does not contact Braintree.	-

Test mode is the main RestroPress Test Mode option, not a setting of this plugin: Test Mode on uses the Braintree sandbox environment, off uses production. The Public Key and Private Key fields are mandatory in both modes, and the keys must come from the matching Braintree environment.

How it works#

1. The customer picks Braintree at checkout and sees a "Credit / Debit Card" form with Card Number, Cardholder Name, Expiration Date and CVC fields, each rendered inside a Braintree iframe. The form notes "Accepted: Visa, Mastercard, Amex." Logged-in customers with saved cards see them as radio buttons, plus "Use a new card". If Saved Cards is on and the customer is logged in, a checkbox "Save this card securely with Braintree for future orders." appears.
2. When the customer places the order, the browser turns the card into a one-time nonce. With 3D Secure on, the customer is taken through verification first. Saved cards skip 3D Secure.
3. The plugin creates the order with status Pending, then sends a sale to Braintree for the cart total, with the purchase key as the order ID, and with submit for settlement on. If the customer asked to save the card, it is stored in the Braintree vault together with the customer's name and email.
4. If Braintree reports the transaction as authorized, submitted for settlement, settling, settlement pending or settled, the transaction ID is saved on the order with the note "Braintree transaction ID", the order is marked Completed, the cart is emptied and the customer sees the success page.
5. If Braintree declines or reports an error, the order is marked failed, Braintree's message is recorded in the gateway error log, and the customer returns to checkout with "Payment failed: ...".
6. Later, Braintree webhooks add a note to the order for every notification. A settled, settlement-confirmed or disbursed notification marks the order Completed. A settlement-declined, settlement-failed or voided notification marks it failed.

Saved cards are stored as a label (for example "Visa ending in 4242") and the Braintree token in the user's profile data. Card numbers never reach your server.

Refunds#

The plugin has no refund code. Changing an order to Refunded in RestroPress changes only its status. Refund or void the transaction in the Braintree Control Panel.

Developer reference#

Hook	Type	Parameters	Purpose
rpress_braintree_settings	filter	$braintree_settings	Add, remove or change the gateway's settings fields.
rpress_braintree_cc_form	action	none	Renders the card form (the plugin hooks its own output here).
rpress_braintree_test_connection	action	$args	Renders the Test Connection button on the settings screen.

The plugin also registers the REST route /wp-json/rpress-braintree/v1/webhook (GET and POST, open to the public; requests are checked by Braintree signature) and the admin action admin-post.php?action=rpress_braintree_test_connection (nonce-protected, for users who can manage shop settings).

add_filter( 'rpress_braintree_settings', function ( $settings ) {
    unset( $settings['braintree_merchant_account_id'] );
    return $settings;
} );

Troubleshooting#

• "Braintree checkout authorization is missing. Add a tokenization key, or enable 3D Secure with complete API credentials." Shown in place of the card form. Enter the Tokenization Key, or turn on 3D Secure and fill in Merchant ID, Public Key and Private Key.
• "Braintree configuration is incomplete." Merchant ID, Public Key or Private Key is empty when the order is placed.
• "Payment method nonce missing. Please try again." The browser did not produce a token, usually because the Braintree scripts did not load. Check for a caching or script-optimisation plugin and reload checkout.
• "Unable to load the secure Braintree card fields." Braintree's scripts were blocked or failed; also check the keys match the active mode.
• "3D Secure verification is required for this card." 3D Secure is on and the browser did not return a verified result.
• "Payment gateway error. Please try again." The Braintree SDK call threw an error; the detail is in the gateway error log and the PHP error log.
• Webhooks rejected. A 403 with "Invalid Braintree webhook signature." means the Public or Private Key does not match the Control Panel that sends the notification (sandbox versus production). Missing fields return 400.