Braintree Payment Provider for Medusa

This plugin integrates Braintree as a payment provider for your Medusa store. It allows you to process payments, handle 3D Secure authentication, and manage payment methods seamlessly.

Quick Start

1. Install the plugin:

   npm install @lambdacurry/medusa-payment-braintree

2. Set the required environment variables in your .env file (see below).
3. Add the provider to your medusa-config.js or config.ts (see below).
4. Add the required custom fields in your Braintree dashboard (see below).
5. Restart your Medusa server.

Features

• Secure payment processing with Braintree.
• Support for 3D Secure authentication.
• Webhook handling for payment updates.
• Save payment methods for future transactions.

Installation

Install the plugin in your Medusa project:

npm install @lambdacurry/medusa-payment-braintree

Configuration

Environment Variables

Set the following environment variables in your .env file:

BRAINTREE_PUBLIC_KEY=<your_public_key>
BRAINTREE_MERCHANT_ID=<your_merchant_id>
BRAINTREE_PRIVATE_KEY=<your_private_key>
BRAINTREE_WEBHOOK_SECRET=<your_webhook_secret>
BRAINTREE_ENVIRONMENT=sandbox|development|production|qa
BRAINTREE_ENABLE_3D_SECURE=true|false

• BRAINTREE_PUBLIC_KEY: Your Braintree public key.
• BRAINTREE_MERCHANT_ID: Your Braintree merchant ID.
• BRAINTREE_PRIVATE_KEY: Your Braintree private key.
• BRAINTREE_WEBHOOK_SECRET: Secret for validating Braintree webhooks.
• BRAINTREE_ENVIRONMENT: One of sandbox, development, production, or qa.
• BRAINTREE_ENABLE_3D_SECURE: Set to true to enable 3D Secure authentication, otherwise false.

Medusa Configuration

Add the following configuration to the payment section of your medusa-config.js or config.ts file:

dependencies:[Modules.CACHE]
{
  resolve: '@lambdacurry/medusa-payment-braintree/providers/payment-braintree',
  id: 'braintree',
  options: {
    environment: process.env.BRAINTREE_ENVIRONMENT || (process.env.NODE_ENV !== 'production' ? 'sandbox' : 'production'),
    merchantId: process.env.BRAINTREE_MERCHANT_ID,
    publicKey: process.env.BRAINTREE_PUBLIC_KEY,
    privateKey: process.env.BRAINTREE_PRIVATE_KEY,
    webhookSecret: process.env.BRAINTREE_WEBHOOK_SECRET,
    enable3DSecure: process.env.BRAINTREE_ENABLE_3D_SECURE === 'true',
    savePaymentMethod: true, // Save payment methods for future use
    autoCapture: true,        // Automatically capture payments
  }
}

Options

• merchantId: Your Braintree Merchant ID.
• publicKey: Your Braintree Public Key.
• privateKey: Your Braintree Private Key.
• webhookSecret: Secret for validating Braintree webhooks.
• enable3DSecure: Enable 3D Secure authentication (true or false).
• savePaymentMethod: Save payment methods for future use (default: true).
• autoCapture: Automatically capture payments (default: true).

Note:

• autoCapture: If set to true, payments are captured automatically after authorization.
• savePaymentMethod: If set to true, customer payment methods are saved for future use.

3D Secure Setup

If you enable 3D Secure (BRAINTREE_ENABLE_3D_SECURE=true), you may need to make additional changes on your storefront to support 3D Secure flows. Refer to the Braintree 3D Secure documentation for more details.

Webhook Setup

To handle payment updates from Braintree, you need to configure webhooks:

1. In your Braintree dashboard, go to Settings > Webhooks.
2. Add a new webhook and set the URL to your Medusa server's webhook endpoint (e.g., https://your-medusa-server.com/webhooks/braintree).
3. Use the value of BRAINTREE_WEBHOOK_SECRET as the secret for validating incoming webhooks.
4. Make sure your Medusa server is configured to handle Braintree webhook events.

For more information, see the Braintree Webhooks documentation.

Adding Custom Fields in the Braintree Dashboard

To ensure proper integration with Medusa, you need to add the following custom fields in your Braintree dashboard:

1. Navigate to:
   Account Settings → Transactions → Custom Fields

2. Add each custom field:

   • Click the Options button.
   • Click the Add button.
   • Enter the details for each field as shown below:

Note:

• The API Name must be in lowercase.
• Set the Options to "Store and Pass back" for each field.

License

This plugin is licensed under the MIT License.

For more information, visit the Braintree Documentation.