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:

12345678
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
TEST_FORCE_SETTLED=true|false
BRAINTREE_LOGGING=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.
• Copy to clipboardTEST_FORCE_SETTLED: Sandbox only. When set to Copy to clipboardtrue and Copy to clipboardBRAINTREE_ENVIRONMENT=sandbox, the refund flow settles the Braintree transaction via the sandbox testing API before attempting a refund. Use this to exercise the refund path (settled/settling) instead of the void path (authorized/submitted_for_settlement). Defaults to Copy to clipboardfalse. Ignored (with a warning) outside sandbox. Do not enable in production.
• Copy to clipboardBRAINTREE_LOGGING: Optional. Set to Copy to clipboardtrue to enable plugin debug logging. Wire this to the provider Copy to clipboardlogging option in Copy to clipboardmedusa-config.ts (see below). Defaults to Copy to clipboardfalse.

Testing refunds in sandbox

In Braintree sandbox, transactions often remain in Copy to clipboardauthorized or Copy to clipboardsubmitted_for_settlement status until they are settled. The provider routes refunds differently by status:

• Void path: Copy to clipboardauthorized, Copy to clipboardsubmitted_for_settlement
• Refund path: Copy to clipboardsettled, Copy to clipboardsettling

To test the refund path locally without waiting for settlement, set:

12
BRAINTREE_ENVIRONMENT=sandbox
TEST_FORCE_SETTLED=true

When both are set, Copy to clipboardrefundPayment calls Braintree's sandbox Copy to clipboardtesting.settle on the transaction, re-fetches it, then proceeds with Copy to clipboardtransaction.refund. If Copy to clipboardTEST_FORCE_SETTLED=true but the provider environment is not Copy to clipboardsandbox, the settle step is skipped and a warning is logged.

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:

123456789101112131415161718
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'),
    defaultCurrencyCode: "USD",
    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
    allowRefundOnRefunded: false,
    logging: process.env.BRAINTREE_LOGGING === 'true', // Enable plugin debug logs
  }
}

Options

• merchantId: Your Braintree Merchant ID.
• defaultCurrencyCode: An optional field to indicate default currency code
• 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).
• allowRefundOnRefunded: Allow refund attempts on already-refunded imported transactions (default: Copy to clipboardfalse).
• logging: Enable verbose plugin debug logging (Copy to clipboardtrue or Copy to clipboardfalse, default: Copy to clipboardfalse). When Copy to clipboardtrue, the provider logs operation details (initiate, authorize, capture, refund, etc.) and expanded Braintree error context via Medusa's logger with a Copy to clipboard[Braintree] prefix. Set via Copy to clipboardBRAINTREE_LOGGING=true in Copy to clipboard.env or pass Copy to clipboardlogging: true directly in provider options. Disable in production unless actively debugging.

Debug logging

Enable plugin debug logs in Copy to clipboardmedusa-config.ts:

1234
options: {
  // ...
  logging: process.env.BRAINTREE_LOGGING === 'true',
}

Then in Copy to clipboard.env:

1
BRAINTREE_LOGGING=true

What Copy to clipboardlogging: true enables:

• Copy to clipboardlogDebug — operation context for payment flows (e.g. refund input, API responses)
• Copy to clipboardlogErrorDetail — extra Braintree failure details (validation errors, processor response codes, stack traces)

Logs are written through Medusa's Copy to clipboardlogger.info() and appear in the Medusa server output. Ensure Medusa's Copy to clipboardLOG_LEVEL is not set to Copy to clipboarderror if you want to see them (the default Copy to clipboardhttp level includes Copy to clipboardinfo messages).

Upgrading to 0.1.2

Earlier README examples used Copy to clipboardlogging: process.env.NODE_ENV !== 'production' (auto-enabled in development). Current examples use explicit Copy to clipboardBRAINTREE_LOGGING=true / Copy to clipboardlogging: process.env.BRAINTREE_LOGGING === 'true'. If you relied on implicit dev logging, set Copy to clipboardBRAINTREE_LOGGING=true or pass Copy to clipboardlogging: true in provider options.

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.
• Copy to clipboardallowRefundOnRefunded: If set to Copy to clipboardtrue, the imported payment provider will gracefully handle refund attempts on transactions that have already been refunded in Braintree. Instead of throwing an error, it will log a warning and record the refund locally only. This is useful when orders are imported and later refunded directly in Braintree.

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.