> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Braintree

> Accept card payments through Braintree using PaymentKit. PaymentKit handles PCI compliance and securely orchestrates every card operation with Braintree — authorize and capture, void, refunds, off-session subscription renewals, 3-D Secure, and multi-currency charges. Braintree is a PayPal service.

# Set up summary

To accept payments with Braintree in PaymentKit, you will need to:

1. Ask PaymentKit support to enable Braintree on your account
2. Generate Braintree API credentials
3. Connect Braintree to PaymentKit
4. (Optional) Turn on 3-D Secure by editing your Braintree connection
5. (Optional) Add a Braintree merchant account for each non-default currency you charge in

# What Braintree supports in PaymentKit

PaymentKit supports the following with Braintree:

* **Card payments** — one-time and customer-initiated (CIT)
* **Authorize and capture** — including a single partial capture (the uncaptured remainder is released)
* **Void** — of an authorization, or of a captured charge that has not settled yet
* **Refunds** — after the charge has settled; see [Refunds and voids](#refunds-and-voids) below
* **Off-session / merchant-initiated payments (MIT)** — including subscription renewals and dunning retries
* **3-D Secure 2 (3DS2)** — the browser challenge and frictionless flows; see [3-D Secure](#3-d-secure) below
* **Multi-currency** — one currency per Braintree merchant account; see [Multi-currency](#multi-currency) below

> **Note**
>
> Braintree results are confirmed synchronously — PaymentKit reads each charge and
> refund outcome back from Braintree directly, so there is **no webhook to configure**.

# Enable Braintree on your account

Braintree is being rolled out gradually, so it is not self-serve yet. In the **Payment processor** list it appears as **contact support to enable** rather than as a credentials form. Reach out to PaymentKit support to turn Braintree on for your account; once it is enabled you can add a connection and enter your credentials as described below.

# Generate API credentials in Braintree

PaymentKit connects to Braintree over its GraphQL API using your **Merchant ID** and an API **key pair** — a **public key** and a **private key**.

1. Log in to the [Braintree Control Panel](https://www.braintreegateway.com/login) (use the [sandbox Control Panel](https://sandbox.braintreegateway.com/login) for testing)
2. Click the **gear icon** in the top-right corner, then choose **API**
3. Under **API Keys**, generate a new key (or use an existing one), then click **View** to reveal its **Public Key** and **Private Key**
4. Note your **Merchant ID**, shown at the top of the same **API** page

> **Warning**
>
> Treat the **private key** like a password — it is the secret half of the pair. Copy
> it somewhere safe when you reveal it, and never share it or commit it to source
> control.

> **Note**
>
> Your sandbox and production Braintree accounts are separate and each has its own
> Merchant ID and key pair. A Braintree key pair carries no sandbox/production marker,
> so you tell PaymentKit which environment it belongs to when you connect (the
> **Environment** field below).

# Connect Braintree to PaymentKit

1. Navigate to **Orchestration → Payment processors**
2. Click **Add Processor** and select **Braintree**
3. Enter your **Merchant ID**, **Public Key**, and **Private Key**
4. Select the **Environment** — **Sandbox** or **Production** — to match the credentials you generated
5. Turn on **Card** as a payment method
6. (Optional) To turn on **3-D Secure**, edit the connection and switch on **Enable 3-D Secure** (see [3-D Secure](#3-d-secure) below)

> **Warning**
>
> The **Environment** must match your credentials. The environment selects which
> Braintree endpoint PaymentKit calls, so sandbox credentials saved as **Production**
> (or the reverse) fail to connect.

# 3-D Secure

3-D Secure (3DS) adds an issuer authentication step to a card payment and can shift chargeback liability to the issuer. Braintree's 3DS runs in the customer's browser, and it is turned on per connection.

* **Turn it on:** Edit your Braintree connection and switch on **Enable 3-D Secure**. With it off, charges run without a challenge, exactly as before.
* **When it applies:** only customer-present (CIT) checkout charges run 3DS, and a challenge is shown only when the card and issuer require one — many payments clear frictionlessly.
* **Off-session charges:** subscription renewals and dunning retries (MIT) **never** trigger a 3DS challenge.

# Refunds and voids

Braintree draws the line at **settlement**, and PaymentKit picks the right operation for you based on the charge's state:

* **Before a charge settles** — the reversal is a **void**, which cancels the charge in full. A void is all-or-nothing: an unsettled charge cannot be partially reversed.
* **After a charge settles** — the reversal is a **refund**, which can be full or partial.

> **Note**
>
> You cannot refund a charge until it has settled, and you cannot void a charge once it
> has settled. When you reverse a charge in PaymentKit, PaymentKit chooses the void or
> refund path automatically from the charge's current state.

A Braintree refund is acknowledged as submitted for settlement and settles shortly after; PaymentKit records the refund as succeeded on that acknowledgement.

# Multi-currency

Braintree sets a charge's currency from the **merchant account** that processes it — not from a field on the charge. Your Braintree **default merchant account** handles your primary currency (USD for most accounts).

To charge in another currency, add a Braintree merchant account configured for that currency in your Braintree account. PaymentKit reads your Braintree merchant accounts and automatically routes each charge to the active account that matches the payment's currency; USD uses your default account.

> **Warning**
>
> A currency with no **active** Braintree merchant account cannot be charged. Add a
> merchant account for each non-default currency you intend to accept before you charge
> in it.

---