Braintree Setup
This guide details the necessary steps to configure your development environment, Braintree account, and application settings before implementing custom payments using the Braintree platform via cordova-plugin-purchase
v13+ and its required Braintree extension.
Platform Interfaces Change Frequently!
The Braintree control panel interface, SDKs, and requirements change often. This guide provides a general overview but may become outdated.
Always refer to the official Braintree documentation as the primary source:
1. Braintree Account Setup
Sandbox: Sign up for a Braintree Sandbox account for development and testing. This provides test API keys and a simulated environment.
Production: When ready to accept real payments, apply for a Braintree Production account and complete the underwriting process.
2. Retrieve Braintree API Credentials
Log in to your Braintree Control Panel (Sandbox or Production):
Navigate to Settings (gear icon) -> API.
Note down your:
Merchant ID
Public Key
Private Key (Keep this secure! It's used server-side).
You will also find your Tokenization Key here. This key can be used directly in the client-side SDK for basic authorization, primarily suitable for testing or simple integrations. Using Client Tokens generated server-side is recommended for production.
3. Install Dependencies
Install the core purchase plugin AND the Braintree extension plugin.
Also ensure you have base Cordova/Node development tools installed:
Needless to say, make sure you have the tools installed on your machine. During the writing of this guide, I've been using the following environment:
NodeJS v10.12.0
Cordova v8.1.2
macOS 10.14.1
I'm not saying it won't work with different version. If you start fresh, it might be a good idea to use an up-to-date environment.
4. Create or Prepare Cordova Project
Set up your Cordova project and add the required platforms (iOS and/or Android).
Create Project: !INCLUDE "./create-cordova-project.md"
Add Platforms:
5. Configure Android Project (Gradle/Dependencies)
The cordova-plugin-purchase-braintree
extension uses Gradle to manage the native Braintree Android SDK dependencies.
Run
cordova prepare android
.Ensure your project builds successfully (
cordova build android
). Gradle should automatically download the required Braintree libraries.Check the plugin's
plugin.xml
for specific Android SDK version requirements if you encounter build issues related to dependencies.
6. Configure iOS Project (Cocoapods)
The Braintree extension uses Cocoapods for iOS dependencies.
Install Cocoapods: If you don't have it, run
sudo gem install cocoapods
.Navigate and Install: After adding the iOS platform and the plugin, go to your project's
platforms/ios/
directory in the terminal and run:Open Workspace: Always open the
.xcworkspace
file in Xcode, not the.xcodeproj
file, after runningpod install
.Build: Build the project in Xcode to ensure dependencies are linked correctly.
7. Initialize Braintree in Your App
In your application's JavaScript (after deviceready
), you need to initialize the CdvPurchase.store
including the Braintree platform adapter. This requires providing authorization.
Option 1: Using Client Token Provider (Recommended for Production)
This is the most secure method. Your server generates a short-lived Client Token using the Braintree Server SDK (with your Merchant ID, Public Key, and Private Key). Your app requests this token when needed.
Note: You must implement the
/api/braintree/client-token
endpoint on your server using Braintree's server SDKs.
Option 2: Using Tokenization Key (Simpler for Testing)
Use your Sandbox Tokenization Key directly. Do not use this method with your Production Tokenization Key in a publicly distributed app, as it's less secure than Client Tokens.
8. (Optional) Configure Apple Pay (iOS Only)
To enable Apple Pay via Braintree:
Configure Apple Pay in Braintree: Follow Braintree's guide to configure Apple Pay in your Braintree control panel (requires Apple Merchant ID setup).
Enable Apple Pay Capability: In Xcode, under "Signing & Capabilities", add the "Apple Pay" capability and configure your Merchant ID.
Provide Options: Add the
applePay
configuration within thebraintreeOptions
duringstore.initialize
. At minimum,companyName
is often needed.
9. (Optional) Configure Google Pay (Android Only)
To enable Google Pay via Braintree:
Configure Google Pay in Braintree: Follow Braintree's guide to enable Google Pay in your Braintree control panel (may require linking a Google Merchant ID).
Provide Options: Add the
googlePay
configuration within thebraintreeOptions
duringstore.initialize
.
10. (Optional) Configure 3D Secure
To add an extra layer of security for card payments:
Enable 3D Secure in Braintree: Ensure 3D Secure is enabled for your Braintree account.
Provide Options: Add the
threeDSecure
configuration within thebraintreeOptions
. You typically need to provide the amount and potentially billing/shipping details within thestore.requestPayment
call itself, but you can set defaults here.
After completing these steps, your Braintree account and application should be configured to process payments using the cordova-plugin-purchase-braintree
extension and the store.requestPayment()
method. Remember that the crucial step of processing the payment nonce must happen on your server.
Last updated