Вышел Модуль интеграций 2.0 для MedusaЧитать анонс
Braintree logo

Braintree

Поддержка платежей и 3D Secure через Braintree

npm install @lambdacurry/medusa-payment-braintree
Категория
Создано
Сервис
Версия
0.2.6
Последнее обновление
1 месяц назад
Ежемесячные загрузки
Загрузка данных

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:
  2. Set the required environment variables in your file (see below).
  3. Add the provider to your or (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:

Configuration

Environment Variables

Set the following environment variables in your file:

  • : Your Braintree public key.
  • : Your Braintree merchant ID.
  • : Your Braintree private key.
  • : Secret for validating Braintree webhooks.
  • : One of , , , or .
  • : Set to to enable 3D Secure authentication, otherwise .
  • : Optional. Set to to enable plugin debug logging. Wire this to the provider option in (see below). Defaults to .
  • : Optional. Sandbox only. Wire this to the provider option in (see below). Defaults to . Do not enable in production.

Testing refunds in sandbox

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

  • Void path: ,
  • Refund path: ,

To test the refund path locally without waiting for settlement, set and in provider options (optionally via env):

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

Medusa Configuration

Add the following configuration to the section of your or file:

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 ( or ).
  • savePaymentMethod: Save payment methods for future use (default: ).
  • autoCapture: Automatically capture payments (default: ).
  • allowRefundOnRefunded: Allow refund attempts on already-refunded imported transactions (default: ).
  • disableVoidTransactions: When , refunds never void; only / transactions may be refunded. Late requirement so future partial order refunds and order edits can be supported (void cancels the full authorization). Default: . With this enabled, / refunds fail with (“cannot be refunded right now because it's in status …”); other non-refundable statuses fail with (“cannot be refunded because it's in status …”).
  • logging: Enable verbose plugin debug logging ( or , default: ). When , the provider logs operation details (initiate, authorize, capture, refund, etc.) and expanded Braintree error context via Medusa's logger with a prefix. Set via in or pass directly in provider options. Disable in production unless actively debugging.
  • testForceSettled: Sandbox only. When and is , 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 . Ignored (with a warning) outside sandbox. Set via in wired to this option, or pass directly. Do not enable in production.

Debug logging

Enable plugin debug logs in :

Then in :

BRAINTREE_LOGGING=true

What enables:

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

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

Upgrading to 0.1.2

Earlier README examples used (auto-enabled in development). Current examples use explicit / . If you relied on implicit dev logging, set or pass in provider options.

Note:

  • : If set to , payments are captured automatically after authorization.
  • : If set to , customer payment methods are saved for future use.
  • : If set to , 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.

Upgrading to 0.2.5

Note:

  • Sequential partial refunds keep the original sale on . Credit/void results are recorded only on . If you were reading the latest credit from after a refund, use instead.
  • Refund rejection errors now include the Braintree transaction status in the message.

Upgrading to 0.2.2

Note:

  • : Late additional requirement so future partial order refunds and order edits can be supported. When , only / may be refunded; / fail with (“cannot be refunded right now because it's in status …”); other statuses fail with (“cannot be refunded because it's in status …”). may still void.

3D Secure Setup

If you enable 3D Secure (), 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., ).
  3. Use the value of 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 via .

  1. Navigate to:
    → →

  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)DescriptionOptions
Medusa Payment Session IdMedusa Session IdStore and Pass back
Cart IdCart IdStore and Pass back
Customer IdCustomer IdStore 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 , include that key in when you call .

Passing Custom Fields to authorizePayment

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

Example:

Requirements and tips:

  • Provide as an object of .
  • Only fields that exist in Braintree will be accepted.
  • For webhook correlation, set to your Medusa payment session or idempotency key.

Implementation detail: the provider passes directly to Braintree’s in the sale request ().

License

This plugin is licensed under the MIT License.

For more information, visit the Braintree Documentation.