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:

Ask PaymentKit support to enable Braintree on your account
Generate Braintree API credentials
Connect Braintree to PaymentKit
(Optional) Turn on 3-D Secure by editing your Braintree connection
(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 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 below
Multi-currency — one currency per Braintree merchant account; see Multi-currency below

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.

Log in to the Braintree Control Panel (use the sandbox Control Panel for testing)
Click the gear icon in the top-right corner, then choose API
Under API Keys, generate a new key (or use an existing one), then click View to reveal its Public Key and Private Key
Note your Merchant ID, shown at the top of the same API page

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.

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

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

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.

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.

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.