> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_braintrees.md).

# Payment setting braintrees

The payment setting braintree object and the allowed CRUD operations on the related resource endpoint

Braintree payment settings are the Braintree-specific subtype of [payment settings](/core-api-reference/2026-05/payment_settings.md). They hold the credentials and configuration required to process payments through the [Braintree](https://www.braintreepayments.com) payment gateway via its GraphQL API.

## Credentials

Setting up a Braintree payment setting requires the following credential attributes:

<table><thead><tr><th width="220">Attribute</th><th>Description</th><th width="100" data-type="checkbox">Required</th></tr></thead><tbody><tr><td><strong><code>merchant_id</code></strong></td><td>Your Braintree merchant ID.</td><td>true</td></tr><tr><td><strong><code>public_key</code></strong></td><td>Braintree API public key.</td><td>true</td></tr><tr><td><strong><code>private_key</code></strong></td><td>Braintree API private key.</td><td>true</td></tr><tr><td><strong><code>merchant_account_id</code></strong></td><td>The specific merchant account to use for transactions.</td><td>true</td></tr></tbody></table>

## Gateway versions

Braintree payment settings support the following gateway version, corresponding to Braintree's GraphQL API version:

* `2019-01-01` (default)

## Capabilities

Braintree payment settings support the following Commerce Layer features:

<table><thead><tr><th>Feature</th><th width="100" data-type="checkbox">Supported</th></tr></thead><tbody><tr><td>Payment sessions</td><td>true</td></tr><tr><td>Payment wallets</td><td>true</td></tr><tr><td>Payment links</td><td>false</td></tr><tr><td>3DS / SCA</td><td>true</td></tr></tbody></table>

## Client-side integration

Braintree requires payment details to be collected client-side using its Drop-in UI or JS SDK. Once the customer completes the form, payment details must be submitted back (more details [here](/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

## Wallet vaulting

When a payment wallet is created against a Braintree payment setting without a `customer_token` supplied, Commerce Layer first creates a customer profile on Braintree and stores its ID as the wallet's customer token. The payment method is associated with that profile as part of the same request that vaults it. If you supply it yourself instead, it must already be a valid Braintree customer ID.

{% hint style="info" %}
You can find more information about how this compares to the other payment providers [here](/core-api-reference/2026-05/payment_wallets.md#token-references).
{% endhint %}

## Webhook events

Commerce Layer listens to the following Braintree webhook notification events, sent to the `webhook_endpoint_url` attribute exposed on this resource — configure it in the [Braintree Control Panel](https://developer.paypal.com/braintree/articles/control-panel/webhooks) so Braintree can deliver notifications to Commerce Layer:

<table><thead><tr><th width="330">Event</th><th>Action</th></tr></thead><tbody><tr><td><strong><code>transaction-settled</code></strong></td><td>Creates or updates a payment capture — <code>succeeded</code> — or, if the underlying Braintree transaction is a credit, a payment refund — <code>succeeded</code>.</td></tr><tr><td><strong><code>transaction-settlement-declined</code></strong></td><td>Creates or updates a payment capture — <code>failed</code> — or, if the underlying Braintree transaction is a credit, a payment refund — <code>failed</code>.</td></tr><tr><td><strong><code>local-payment-completed</code></strong></td><td>Creates a payment authorization and a payment capture — both <code>succeeded</code>.</td></tr></tbody></table>

Whether a capture or a refund is created depends on the Braintree transaction type:

* A `sale` transaction maps to a payment capture.
* A `credit` transaction maps to a payment refund.

Events are matched to a payment session using the Braintree transaction ID — which Commerce Layer stores on the related payment transaction when it calls Braintree — or, for local payments, the `payment_id`. If the event refers to a session but the transaction doesn't already exist on Commerce Layer, it's created automatically.

{% hint style="warning" %}
Only transactions started through the Commerce Layer API can be reconciled. Transactions created directly on Braintree (e.g. a refund issued from the Braintree Control Panel) aren't known to Commerce Layer, so their events can't be matched to a payment session and are ignored.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/payment_setting_braintrees.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.