Set up Braintree

1. Add Braintree in Carden

Select the merchant and Carden environment used by your Braintree backend. Open Integrations, add Braintree, and open its Setup page. Use a sandbox workspace with Braintree sandbox keys and a production workspace with production keys.

2. Create a restricted Braintree API user

1. In the Braintree Control Panel, create a custom role that can only view transactions.
2. Create a dedicated API user and assign it that role. Do not reuse a person's login or an administrator account.
3. Sign in as that user and open Settings (gear) → API.
4. Select Generate New API Key, then View.
5. Copy the Merchant ID, Public Key, and Private Key.

3. Verify and connect

Paste the Merchant ID, Public Key, and Private Key into Carden Setup and select Verify and connect. Carden checks the keys with Braintree before saving, encrypts them, and never shows the private key again.

• Keys from the wrong Braintree environment fail with an authentication error.
• A role without transaction view access fails with an authorization error.
• A Braintree merchant can be connected to only one Carden workspace.

4. Add the Carden webhook in Braintree

1. After connecting, copy the destination URL shown under Webhook delivery.
2. In the Braintree Control Panel, open Settings (gear) → API → Webhooks → Create new webhook.
3. Paste the destination URL and select Transaction Settled, Transaction Settlement Declined, Transaction Disbursed, Dispute Opened, Dispute Lost, and Dispute Won.
4. Select Create Webhook.
5. Select Check URL next to the new webhook. Braintree sends a signed check notification and the Carden status changes from Awaiting first notification to Delivery verified.

The destination URL must be public HTTPS. Braintree signs each notification with your API key pair, so Carden verifies it with the stored keys. Refunds arrive as settled credit transactions. Braintree webhooks omit line items, so after a sale settles Carden reads its retained line-item count with the restricted key.

5. Connect QuickBooks

Connect QuickBooks so Carden can prepare Level 2/3 fields from authoritative invoices. Let the initial import complete and resolve factual invoice and item-mapping exceptions. Without QuickBooks, you can still send a complete CanonicalInvoice v1 inline.

6. Create a Carden server key

Create a Braintree-integration Carden API key and store it in your server's secret manager. A Stripe, Square, or QuickBooks key is rejected even if it has a similarly named scope.

Backend flow

1. Look up the invoice your customer is paying and persist a payment attempt with a stable preparation idempotencyKey.
2. Call Carden to prepare Braintree fields for the full invoice amount in USD.
3. Merge data into gateway.transaction.sale, or into gateway.transaction.submitForSettlement for an authorization you captured later. Keep preparation.id with the attempt.
4. Report the Braintree outcome to Carden with enrichmentRequestId set to preparation.id.
5. Carden records settlement, refunds, disputes, and card classification from signed Braintree webhooks.

POST /api/v1/braintree/transaction-enrichment/from-invoice
POST /api/v1/braintree/transaction-enrichment
POST /api/v1/braintree/payment-reports

If Carden reports a PO, SKU, or unit gap, take the payment as an ordinary Braintree transaction without Level 2/3 fields. Carden never invents a PO number, SKU, unit, or tax amount to fill a field.

Rotate or disconnect

To rotate keys, generate a new API key for the same API user in Braintree, select Rotate API keys in Carden, and paste the new values. The webhook destination URL is kept, so the Braintree webhook needs no change. Then revoke the old key in Braintree.

Select Disconnect to stop accepting webhooks immediately. Payment evidence Carden already recorded is kept. Delete the webhook in Braintree too.