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:

123456789101112131415
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 (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 use custom fields, create them in your Braintree dashboard (API names must be lowercase). You will provide their values when calling Copy to clipboardauthorizePayment via Copy to clipboardcontext.custom_fields.

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 (example) API Name (example) 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

• Braintree only accepts values for custom fields that exist in your dashboard and match the field API names (lowercase).
• If you rely on webhooks that read Copy to clipboardmedusa_payment_session_id, include that key in Copy to clipboardcontext.custom_fields when you call Copy to clipboardauthorizePayment.

Passing Custom Fields to authorizePayment

Custom fields are forwarded to Braintree when the provider creates the transaction during Copy to clipboardauthorizePayment. Provide them on the Copy to clipboardcontext as Copy to clipboardcustom_fields.

Example:

123456789101112131415161718
// Example shape; Medusa calls the provider under the hood.
await braintreeProvider.authorizePayment({
  data: {
    amount: 10, // standard currency units; converted to "10.00"
    currency_code: 'USD',
    payment_method_nonce: '<client-side-nonce>',
  },
  context: {
    idempotency_key: 'sess_123',
    customer: { id: 'cust_123', email: 'c@example.com' },
    custom_fields: {
      medusa_payment_session_id: 'sess_123',
      cart_id: 'cart_123',
      customer_id: 'cust_123',
    },
    // Optional: shipping_address, billing_address, totals, items
  },
});

Requirements and tips:

• Provide Copy to clipboardcustom_fields as an object of Copy to clipboardAPI name -> string value.
• Only fields that exist in Braintree will be accepted.
• For webhook correlation, set Copy to clipboardmedusa_payment_session_id to your Medusa payment session or idempotency key.

Implementation detail: the provider passes Copy to clipboardcontext.custom_fields directly to Braintree’s Copy to clipboardcustomFields in the sale request (Copy to clipboardplugins/braintree-payment/src/providers/payment-braintree/src/core/braintree-base.ts:402).

License

This plugin is licensed under the MIT License.

For more information, visit the Braintree Documentation.