Braintree

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:

1
npm install @lambdacurry/medusa-payment-braintree

1. Set the required environment variables in your Copy to clipboard.env file (see below).
2. Add the provider to your Copy to clipboardmedusa-config.js or Copy to clipboardconfig.ts (see below).
3. Add the required custom fields in your Braintree dashboard (see below).
4. 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:

1
npm install @lambdacurry/medusa-payment-braintree

Configuration

Environment Variables

Set the following environment variables in your Copy to clipboard.env file:

123456
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

• Copy to clipboardBRAINTREE_PUBLIC_KEY: Your Braintree public key.
• Copy to clipboardBRAINTREE_MERCHANT_ID: Your Braintree merchant ID.
• Copy to clipboardBRAINTREE_PRIVATE_KEY: Your Braintree private key.
• Copy to clipboardBRAINTREE_WEBHOOK_SECRET: Secret for validating Braintree webhooks.
• Copy to clipboardBRAINTREE_ENVIRONMENT: One of Copy to clipboardsandbox, Copy to clipboarddevelopment, Copy to clipboardproduction, or Copy to clipboardqa.
• Copy to clipboardBRAINTREE_ENABLE_3D_SECURE: Set to Copy to clipboardtrue to enable 3D Secure authentication, otherwise Copy to clipboardfalse.

Medusa Configuration

Add the following configuration to the Copy to clipboardpayment section of your Copy to clipboardmedusa-config.js or Copy to clipboardconfig.ts file:

1234567891011121314
{
  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 (Copy to clipboardtrue or Copy to clipboardfalse).
• savePaymentMethod: Save payment methods for future use (default: Copy to clipboardtrue).
• autoCapture: Automatically capture payments (default: Copy to clipboardtrue).

Note:

• Copy to clipboardautoCapture: If set to Copy to clipboardtrue, payments are captured automatically after authorization.
• Copy to clipboardsavePaymentMethod: If set to Copy to clipboardtrue, customer payment methods are saved for future use.

3D Secure Setup

If you enable 3D Secure (Copy to clipboardBRAINTREE_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., Copy to clipboardhttps://your-medusa-server.com/webhooks/braintree).
3. Use the value of Copy to clipboardBRAINTREE_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:
   Copy to clipboardAccount Settings → Copy to clipboardTransactions → Copy to clipboardCustom Fields
2. Add each custom field:
   • Click the Options button.
   • Click the Add button.
   • Enter the details for each field as shown below:

Field Name API Name Description Options Medusa Payment Session Id Copy to clipboardmedusa_payment_session_id Medusa Session Id Store and Pass back Cart Id Copy to clipboardcart_id Cart Id Store and Pass back Customer Id Copy to clipboardcustomer_id Customer Id Store and Pass back

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.