> 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/how-tos/placing-orders/payments/braintree/accepting-local-payments.md).

# Accepting local payments

How to support Braintree local payments

## Problem

You want to allow your customers to checkout with the Braintree-supported [local payment methods](https://developers.braintreepayments.com/guides/local-payment-methods/overview). You've properly [configured](https://developers.braintreepayments.com/guides/local-payment-methods/configuration/javascript/v3) your account in the Braintree control panel and integrated their client [SDK](https://developers.braintreepayments.com/guides/local-payment-methods/client-side-custom/javascript/v3). You now need to set up the payment source in order to support the different local payment workflows.

## Solution

The first steps to setup local payments are similar to the standard ones, with the only notable difference you need to set the `local` attribute as `true` when you create the payment source.

{% content-ref url="/pages/-MMzwmwMyD6AvQOH6lSu" %}
[Adding the payment source](/how-tos/placing-orders/payments/braintree/adding-the-payment-source.md)
{% endcontent-ref %}

After that, paths differ based on two possible scenarios — whether the customer is [returning to your checkout](#customer-returning-to-your-checkout) or [not](#customers-leaving-your-site-after-payment).

### Customers returning to your checkout

Assuming the customer goes back to your checkout application, you need to update the payment source with the `payment_method_nonce` returned by Braintree as with standard payments.

{% content-ref url="/pages/-MN3I07NWLU903sluyVG" %}
[Sending back the payment method nonce](/how-tos/placing-orders/payments/braintree/sending-back-the-payment-method-nonce.md)
{% endcontent-ref %}

Then you have just to update the order with the `_place` attribute in order to complete the payment.

{% content-ref url="/pages/-LyDmx1SH-gJp8DstXnO" %}
[Placing the order](/how-tos/placing-orders/checkout/placing-the-order.md)
{% endcontent-ref %}

{% hint style="info" %}
Upon successful response by Braintree, the order will be captured and approved automatically, since the transaction is already settled by the local payment gateway chosen by the customer.
{% endhint %}

### Customers leaving your site after payment

If the customer doesn't return to your checkout application, you need to follow a slightly different workflow:

1. Configure [Braintree webhooks](https://developers.braintreepayments.com/guides/webhooks/overview) to notify Commerce Layer about the payment results — to do that, use the `webhook_endpoint_url` exposed by the Braintree gateway resource.
2. Update it with the `payment_id` returned by the client [SDK](https://developers.braintreepayments.com/guides/local-payment-methods/client-side-custom/javascript/v3#start-the-payment), in order to let our webhook find and update the payment source used for the payment.
3. Monitor the order's status, since our webhook will update the payment source with the `payment_method_nonce`, place the order, and — upon successful response by Braintree — capture and approve it in a single step.

### Example

#### 1. Create the local payment source

{% tabs %}
{% tab title="Request" %}
The following request creates a Braintree payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

```javascript
curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/braintree_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "braintree_payments",
    "attributes": {
      "local": true
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "qaMAhZkZvd"
        }
      }
    }
  }
}'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created Braintree payment object:

```javascript
{
  "data": {
    "id": "vdDEAsZYzR",
    "type": "braintree_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR"
    },
    "attributes": {
      "client_token": "xxxx.yyyy.zzzz",
      "payment_method_nonce": null,
      "payment_id": null,
      "local": true,
      "options": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "Uv0wXyZaAb",
      "trace_id": "2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8"
    }
  },
  "meta": {
    "mode": "test",
    "organization_id": "Uv0wXyZaAb",
    "trace_id": "2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8"
  }
}
```

{% endtab %}
{% endtabs %}

#### 2. Update the payment source with the payment ID

{% tabs %}
{% tab title="Request" %}
The following request updates the Braintree payment source identified by the "vdDEAsZYzR" ID with the `payment_id` received from the client:

```javascript
curl -g -X PATCH \
  'http://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "braintree_payments",
    "id": "vdDEAsZYzR",
    "attributes": {
      "payment_id": "xxxx.yyyy.zzzz"
    }
  }
}'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated Braintree payment object:

```javascript
{
  "data": {
    "id": "vdDEAsZYzR",
    "type": "braintree_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR"
    },
    "attributes": {
      "client_token": "xxxx.yyyy.zzzz",
      "payment_method_nonce": null,
      "payment_id": "xxxx.yyyy.zzzz",
      "local": true,
      "options": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "Uv0wXyZaAb",
      "trace_id": "2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8"
    }
  },
  "meta": {
    "mode": "test",
    "organization_id": "Uv0wXyZaAb",
    "trace_id": "2b5c8d1e4f7a0b3c6d9e2f5a8b1c4d7e0f3a6b9c2d5e8f1a4b7c0d3e6f9a2b5c8"
  }
}
```

{% endtab %}
{% endtabs %}

## More to read

See our documentation if you need more information on how to [create](https://docs.commercelayer.io/developers/v/api-reference/braintree_payments/create) and [update a Braintree payment](https://docs.commercelayer.io/developers/v/api-reference/braintree_payments/update) or if you need to learn more about [Braintree gateways](https://docs.commercelayer.io/developers/v/api-reference/braintree_gateways).


---

# 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/how-tos/placing-orders/payments/braintree/accepting-local-payments.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.