> 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](https://docs.commercelayer.io/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="240">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><tr><td><strong><code>google_pay_merchant_id</code></strong></td><td>Your Google Pay merchant ID, issued by the <a href="https://pay.google.com/business/console">Google Pay &#x26; Wallet Console</a> — needed only to offer Google Pay in production.</td><td>false</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](https://docs.commercelayer.io/core-api-reference/2026-05/payment_authorizations.md#handling-3ds-and-customer-action)).

### Google Pay

To offer Google Pay in production, set the payment setting's `google_pay_merchant_id` and pass it as `googleMerchantId` when creating the Google Pay component with Braintree's JS SDK (more details [here](https://developer.paypal.com/braintree/docs/guides/google-pay/client-side/javascript/v3/)). The attribute is readable with [sales channel](https://docs.commercelayer.io/core/api-credentials.md#sales-channel) API credentials — on the payment setting itself or through the order's `available_payment_settings` — so your checkout can read it without exposing any private credential. In sandbox, Google Pay works without it.

{% hint style="info" %}
Apple Pay needs no attribute on the payment setting: it's set up on the Braintree side, as described in [Braintree's Apple Pay guide](https://developer.paypal.com/braintree/articles/guides/payment-methods/apple-pay).
{% endhint %}

## Wallet vaulting

When a payment wallet is created against a Braintree payment setting, Commerce Layer reuses the Braintree customer profile from the customer's latest wallet on the same payment setting, or creates a new one 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.

Cards are verified on the payment setting's `merchant_account_id` before being stored, so a card the merchant account can't charge is rejected when the wallet is created rather than on its first payment.

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

### Vaulting during a payment

When a [payment session](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#vaulting-during-a-charge) has vaulting enabled, Commerce Layer asks Braintree to store the payment method along with the authorization (or the charge, with `auto_capture` enabled), since Braintree consumes a single-use payment method as soon as it's used and can't store it afterwards. Braintree stores it only if the payment succeeds, and Commerce Layer creates the wallet from the returned payment method, already `succeeded` and linked to the session.

If the customer already holds a Braintree customer profile on the same payment setting, the new payment method is added to it. Otherwise, Braintree creates the profile from the customer's email at the moment the payment method is stored — a declined or abandoned payment leaves neither a wallet nor an empty customer profile behind.

{% hint style="warning" %}
Vaulting is skipped for orders without a customer and for sessions already paying with a wallet: the session is paid all the same, but no wallet is created.
{% endhint %}

### Duplicate wallets

Braintree stores a new payment method every time an instrument is vaulted, even when it's one the customer already saved, so each vaulting creates a separate wallet with its own token.

## Capture and refund outcomes

Captures and refunds resolve synchronously for Braintree. A transaction that Braintree accepts and submits for settlement is recorded as `succeeded` straight away, without waiting for settlement to complete. With `auto_capture` enabled, the payment is charged in a single step, and the resulting capture succeeds alongside the authorization.

Braintree refunds a transaction only once it's settling or settled. Creating a refund on a capture that's still submitted for settlement fails with Braintree's error, and can be retried once the capture has settled.

{% hint style="warning" %}
Braintree sends settlement webhook events only for ACH Direct Debit and SEPA Direct Debit transactions, so cards, PayPal, and Venmo never get a later confirmation. For ACH and SEPA, a capture or refund that's already succeeded can still be moved to the `failed` status if Braintree reports the settlement as declined. For every other payment method, use the `_refresh` trigger to pick up later changes (more details [here](#refreshing-a-payment-session)).
{% endhint %}

## Order reference

Every authorization or charge sent to Braintree carries an `orderId` made of the order number followed by the ID of the payment authorization (e.g. `12345678-xYZkjABcDe`). It's unique for each attempt, so a retried payment never reuses the reference of a previous one.

{% hint style="info" %}
You can still set your own `orderId` via the session's [gateway options](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#gateway-options) — it takes precedence over the default.
{% endhint %}

## Recurring payments

Commerce Layer sets Braintree's `paymentInitiator` on the payments of a subscription:

* `RECURRING_FIRST` — on the payment that stores the instrument for an order with recurring [line items](https://docs.commercelayer.io/core-api-reference/2026-05/line_items.md#choosing-line-items-that-generate-subscriptions), marking the start of the series.
* `RECURRING` — on each [renewal](https://docs.commercelayer.io/core-api-reference/2026-05/order_subscriptions.md#unattended-renewals) charged on a stored instrument, as a merchant-initiated payment.

Other payments carry no initiator, unless you set one yourself via the session's [gateway options](https://docs.commercelayer.io/core-api-reference/2026-05/payment_sessions.md#gateway-options).

## Refreshing a payment session

Sending the `_refresh` trigger attribute on a payment session asks Braintree for the current state of its transaction and aligns the session with it. This also picks up operations made directly in the [Braintree Control Panel](https://developer.paypal.com/braintree/articles/control-panel/search):

* **Voids** — if the transaction was voided on Braintree, a payment void is created as `succeeded`.
* **Captures** — if the session has no capture yet, one is created with the status matching Braintree's: `succeeded` once the transaction is submitted for settlement, or `failed`, `declined`, or `expired` if Braintree reports the transaction as failed, declined, or with an expired authorization. Existing captures follow their Braintree status — e.g. one whose settlement was declined is moved to `failed`.
* **Refunds** — refunds issued on Braintree against a known capture are created, and existing ones follow their Braintree status.

The refresh only applies to sessions with a successful authorization recorded on Commerce Layer. Transactions that are already `failed`, `declined`, `canceled`, or `expired` are left unchanged.

{% hint style="warning" %}
Partial captures made in the Braintree Control Panel get a new Braintree transaction ID and aren't picked up by the refresh, nor are the refunds issued against them.
{% 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 a payment capture — <code>succeeded</code> — or, if the underlying Braintree transaction is a credit, a payment refund — <code>succeeded</code>. An existing capture or refund that's already <code>succeeded</code> is left unchanged.</td></tr><tr><td><strong><code>transaction_settlement_declined</code></strong></td><td>Creates a payment capture — <code>failed</code> — or, if the underlying Braintree transaction is a credit, a payment refund — <code>failed</code>. An existing capture or refund is moved from <code>succeeded</code> to <code>failed</code>.</td></tr><tr><td><strong><code>local_payment_completed</code></strong></td><td>Creates a payment authorization — unless a <code>succeeded</code> one already exists — and a payment capture, both <code>succeeded</code>.</td></tr><tr><td><strong><code>local_payment_funded</code></strong></td><td>Creates a payment authorization — <code>succeeded</code> — unless one already exists, and, if Braintree has already submitted the transaction for settlement, a payment capture — <code>succeeded</code>.</td></tr><tr><td><strong><code>local_payment_expired</code></strong></td><td>Moves an <code>unpaid</code> payment session to <code>invalidated</code>.</td></tr><tr><td><strong><code>local_payment_reversed</code></strong></td><td>Creates a payment refund — <code>succeeded</code> — for the whole captured amount if the payment was captured, moves the payment authorization to <code>failed</code> if it was only authorized, or moves an <code>unpaid</code> payment session to <code>invalidated</code>.</td></tr></tbody></table>

{% hint style="warning" %}
Local payment events (OXXO, Multibanco, Trustly, and other local payment methods) are ignored once the payment session is already paid, except for `local_payment_reversed`. Make sure all four local payment notifications are enabled in the Braintree Control Panel.
{% endhint %}

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" %}
Webhook events only reconcile transactions started through the Commerce Layer API. Events for transactions created directly on Braintree (e.g. a refund issued from the Braintree Control Panel) can't be matched to a payment session and are ignored — use the `_refresh` trigger to pick them up instead (more details [here](#refreshing-a-payment-session)).
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
