> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/payments/integrations/providers/braintree.md).

# Braintree

Connect Braintree to Payments — keys, webhook URL and signing secret.

Braintree (part of PayPal) takes card and wallet payments and subscriptions. Norbix gets its webhooks (subscription charges, settlements, disputes).

## Get your credentials

1. Sign in to the Braintree Control Panel — the [sandbox](https://sandbox.braintreegateway.com/) for tests.
2. Open **Settings (gear) → API → API Keys**. Copy the **Merchant ID** and, under the key, press **View** to copy the **Private Key** (see [Important gateway credentials](https://developer.paypal.com/braintree/articles/control-panel/important-gateway-credentials)).
3. Save the integration in Cloud once (below) to get its **Webhook URL**.
4. Open **Settings → Webhooks → Create new webhook**, paste the webhook URL and pick the notifications (see [Webhooks](https://developer.paypal.com/braintree/docs/guides/webhooks/overview)). Braintree signs the calls with your API keys, so no extra secret is needed.

## Connect it in Cloud

**Where:** Payments → Integrations → **Add New Integration** → Braintree → **Connect** · `/projects/<project>/payments/integrations/new/braintree`

| Field            | Required | What it does                                                                                                                                                           | Example             |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Merchant ID      | yes      | Your Braintree merchant id.                                                                                                                                            | `your-merchant-id`  |
| Environment      | yes      | `sandbox` or `production` — type the word.                                                                                                                             | `sandbox`           |
| Private Key      | yes      | Lets Norbix call Braintree and checks the `bt_signature` of each webhook. Secret; encrypted on save and never shown again — type it again whenever you press **Save**. | `your-private-key`  |
| Integration Name | yes      | The name in your integrations list.                                                                                                                                    | `Braintree sandbox` |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-391abd0b1ee0d9b837681305d2357a8191551840%2Fbraintree-form-1.png?alt=media" alt="New Braintree Integration form filled with example values"><figcaption><p>The filled form (placeholder values).</p></figcaption></figure>

Press **Save**. The page turns into **Editing Braintree integration** with the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**, the integration id (`int_2bIX1mVn1R12kK03HFmF2v`) and the **Webhook URL** — `<Hub address>/v3/payments/webhooks/<account id>/<project id>/braintree/<integration id>`; outside PROD it ends with `?env=<ENV>`. Copy it with its copy button and paste it at Braintree (see **Get your credentials**). **Received webhooks** at the bottom lists every call Braintree makes to it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-4b468ecb89c61c48163d360c129379237e9ea129%2Fbraintree-saved-2.png?alt=media" alt="Editing Braintree integration after Save: ENABLED, NOT TESTED, NOT CONFIRMED, the integration id and the Webhook URL"><figcaption><p>After save: the webhook URL to paste at Braintree.</p></figcaption></figure>

Events Norbix accepts from Braintree (pick them at Braintree and in your [trigger](/codemash/cloud/payments/triggers/new.md)): `subscription_charged_successfully`, `subscription_charged_unsuccessfully`, `subscription_canceled`, `transaction_settled`, `transaction_settlement_declined`, `dispute_opened`.

## Test and set as default

**Test integration** only checks that the merchant id, environment and private key are filled in and well-formed; it does not call Braintree, so it can pass with wrong keys — it passed with made-up values. Send a test notification from Braintree and check **Received webhooks**. See [Test an integration](/codemash/cloud/payments/integrations/test.md). Payments has no default integration — every enabled integration gets its own calls ([Default integration](/codemash/cloud/payments/integrations/set-default.md)).

## Common errors

| Message                             | Cause                                                                  | Fix                                                      |
| ----------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| **Received webhooks** shows **400** | The private key does not belong to the key pair Braintree signed with. | Copy the private key again and **Save**.                 |
| Required                            | An empty required field.                                               | Fill every field.                                        |
| Required                            | A required field is empty — secrets count too on every save.           | Fill the field; type every secret again before **Save**. |

## Do it from code

```ts
const { id } = await norbix.hub.payments.savePaymentsIntegration({
  integration: {
    provider: 'Braintree',
    integrationName: 'Braintree live',
    isEnabled: true,
    merchantId: 'your-merchant-id',
    environment: 'production',
    privateKey: 'your-private-key',
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub payments integration save --integration '{"provider":"Braintree","integrationName":"Braintree live","isEnabled":true,"merchantId":"your-merchant-id","environment":"production","privateKey":"your-private-key"}'
```

The client setup is on the [Payments page](/codemash/cloud/payments.md#use-it-from-code). API: [Save Payments Integration](/codemash/api-reference/payments/integrations/save-payments-integration.md)