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:
   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:

1BRAINTREE_PUBLIC_KEY=<your_public_key>
2BRAINTREE_MERCHANT_ID=<your_merchant_id>
3BRAINTREE_PRIVATE_KEY=<your_private_key>
4BRAINTREE_WEBHOOK_SECRET=<your_webhook_secret>
5BRAINTREE_ENVIRONMENT=sandbox|development|production|qa
6BRAINTREE_ENABLE_3D_SECURE=true|false
7TEST_FORCE_SETTLED=true|false
8BRAINTREE_LOGGING=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.
• TEST_FORCE_SETTLED: Sandbox only. When set to true and BRAINTREE_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 false. Ignored (with a warning) outside sandbox. Do not enable in production.
• BRAINTREE_LOGGING: Optional. Set to true to enable plugin debug logging. Wire this to the provider logging option in medusa-config.ts (see below). Defaults to false.

Testing refunds in sandbox

In Braintree sandbox, transactions often remain in authorized or submitted_for_settlement status until they are settled. The provider routes refunds differently by status:

• Void path: authorized, submitted_for_settlement
• Refund path: settled, settling

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

1BRAINTREE_ENVIRONMENT=sandbox
2TEST_FORCE_SETTLED=true

When both are set, refundPayment calls Braintree's sandbox testing.settle on the transaction, re-fetches it, then proceeds with transaction.refund. If TEST_FORCE_SETTLED=true but the provider environment is not sandbox, the settle step is skipped and a warning is logged.

Medusa Configuration

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

1dependencies:[Modules.CACHE]
2{
3  resolve: '@lambdacurry/medusa-payment-braintree/providers/payment-braintree',
4  id: 'braintree',
5  options: {
6    environment: process.env.BRAINTREE_ENVIRONMENT || (process.env.NODE_ENV !== 'production' ? 'sandbox' : 'production'),
7    defaultCurrencyCode: "USD",
8    merchantId: process.env.BRAINTREE_MERCHANT_ID,
9    publicKey: process.env.BRAINTREE_PUBLIC_KEY,
10    privateKey: process.env.BRAINTREE_PRIVATE_KEY,
11    webhookSecret: process.env.BRAINTREE_WEBHOOK_SECRET,
12    enable3DSecure: process.env.BRAINTREE_ENABLE_3D_SECURE === 'true',
13    savePaymentMethod: true, // Save payment methods for future use
14    autoCapture: true,        // Automatically capture payments
15    allowRefundOnRefunded: false,
16    logging: process.env.BRAINTREE_LOGGING === 'true', // Enable plugin debug logs
17  }
18}

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 (true or false).
• savePaymentMethod: Save payment methods for future use (default: true).
• autoCapture: Automatically capture payments (default: true).
• allowRefundOnRefunded: Allow refund attempts on already-refunded imported transactions (default: false).
• logging: Enable verbose plugin debug logging (true or false, default: false). When true, the provider logs operation details (initiate, authorize, capture, refund, etc.) and expanded Braintree error context via Medusa's logger with a [Braintree] prefix. Set via BRAINTREE_LOGGING=true in .env or pass logging: true directly in provider options. Disable in production unless actively debugging.

Debug logging

Enable plugin debug logs in medusa-config.ts:

1options: {
2  // ...
3  logging: process.env.BRAINTREE_LOGGING === 'true',
4}

Then in .env:

BRAINTREE_LOGGING=true

What logging: true enables:

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

Logs are written through Medusa's logger.info() and appear in the Medusa server output. Ensure Medusa's LOG_LEVEL is not set to error if you want to see them (the default http level includes info messages).

Upgrading to 0.1.2

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

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.
• allowRefundOnRefunded: If set to true, 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 (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 use custom fields, create them in your Braintree dashboard (API names must be lowercase). You will provide their values when calling authorizePayment via context.custom_fields.

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

• 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 medusa_payment_session_id, include that key in context.custom_fields when you call authorizePayment.

Passing Custom Fields to authorizePayment

Custom fields are forwarded to Braintree when the provider creates the transaction during authorizePayment. Provide them on the context as custom_fields.

Example:

1// Example shape; Medusa calls the provider under the hood.
2await braintreeProvider.authorizePayment({
3  data: {
4    amount: 10, // standard currency units; converted to "10.00"
5    currency_code: 'USD',
6    payment_method_nonce: '<client-side-nonce>',
7  },
8  context: {
9    idempotency_key: 'sess_123',
10    customer: { id: 'cust_123', email: 'c@example.com' },
11    custom_fields: {
12      medusa_payment_session_id: 'sess_123',
13      cart_id: 'cart_123',
14      customer_id: 'cust_123',
15    },
16    // Optional: shipping_address, billing_address, totals, items
17  },
18});

Requirements and tips:

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

Implementation detail: the provider passes context.custom_fields directly to Braintree’s customFields in the sale request (plugins/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.