Braintree OAuth Integration Example

This React TypeScript project demonstrates a Braintree OAuth integration flow between two merchants. It showcases how Merchant A can obtain authorization from Merchant B to perform actions on their behalf using Braintree's OAuth and transaction APIs.

Want to experience it firsthand in your own environment? Simply click the button below to deploy it in a matter of clicks:

To authenticate the OAuth permissions request, a second Braintree account will be necessary for approval.

Overview

In this example, Merchant A provides this application to Merchant B, allowing them to:

• Grant OAuth permissions to Merchant A
• Allow access to customer payment methods
• Enable facilitated transactions
• Create Subscriptions

The integration uses the following Braintree APIs:

• Access Token API - For OAuth authentication
• Grant API - For creating Payment Method Nonces
• Customer API - For creating Customers
• Payment Method API - For creating Payment Methods
• Transaction API - For creating Shared Vault Transactions
• Subscription API - For creating Subscriptions

Features

• OAuth connection flow
• Token management and storage
• Shared vault transaction processing
• Real-time transaction status updates
• Error handling and user feedback

Prerequisites

Before running this application, you'll need:

• Node.js (v16 or higher)
• Yarn package manager
• Braintree sandbox account
• Environment variables (see .env.example)

Installation

1. Clone the repository
2. Install dependencies:

yarn

Configuration

Create a .env file in the root directory with the following variables:

Note: Remove prefix client_id$sandbox$ and client_secret$sandbox$ from environment variable values in the .env file. This prefix is hard-coded within the code to avoid issues with special characters. For example, client_id$sandbox$1234567890 should be 1234567890.

# Client Accessible Environment VariablesVITE_BRAINTREE_ENVIRONMENT=sandboxVITE_BRAINTREE_MERCHANT_ID=MERCHANT_A_MERCHANT_IDVITE_BRAINTREE_OAUTH_CLIENT_ID=MERCHANT_A_OAUTH_CLIENT_IDVITE_BRAINTREE_REDIRECT_URI=http://localhost:5173/oauth-callbackBRAINTREE_ENVIRONMENT=sandbox# Server Environment Variables (Merchant A)BRAINTREE_OAUTH_CLIENT_ID=MERCHANT_A_OAUTH_CLIENT_IDBRAINTREE_OAUTH_CLIENT_SECRET=MERCHANT_A_OAUTH_CLIENT_SECRET# Server Environment Variables (Merchant B)BRAINTREE_MERCHANT_ID=MERCHANT_B_MERCHANT_IDBRAINTREE_PUBLIC_KEY=MERCHANT_B_PUBLIC_KEYBRAINTREE_PRIVATE_KEY=MERCHANT_B_PRIVATE_KEY

Running the Application

# Run Client
yarn client
# Run Server
yarn server
# Run Both
yarn dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend: http://localhost:9090

How It Works

1. Merchant B accesses the application and initiates the OAuth connection
2. They are redirected to Braintree's OAuth consent page
3. Upon authorization, Braintree redirects back with an authorization code
4. The application exchanges this code for access/refresh tokens
5. Merchant A can now process transactions on Merchant B's behalf

API Endpoints

• POST /api/oauth/token - Exchange authorization code for tokens
• POST /api/transactions - Create a shared vault transaction
• POST /api/grant/nonce - Create a payment method nonce
• POST /api/subscriptions - Create a subscription

Security Considerations

• All sensitive credentials are stored in environment variables
• OAuth tokens are securely managed
• CORS is properly configured
• Input validation is implemented

Important

This project is a demonstration and should not be used in production as-is. Ensure that all sensitive information, such as OAuth tokens and API keys, are stored securely and not in local storage. Follow best practices for security and data protection.

Token Storage

For demonstration purposes, the returned access token and refresh token are stored in local storage to demo the create transaction API. However, this would not happen in the real use case of this project. In reality, once Merchant B completes the OAuth approval process, Merchant A's environment of this app should store the access token and refresh token securely so that they can use it to perform actions on Merchant B's behalf as mentioned above. It is highly recommended to store these tokens securely in secure HTTP-only cookies or a secure storage service to prevent potential security vulnerabilities.