Braintree
Prepare Braintree Level 2/3 fields from authoritative invoices, merge them into your own transaction call, and record processor evidence from signed Braintree webhooks.
On this page
Your backend keeps control of Braintree
Carden's Braintree integration is a server-to-server companion for a merchant's existing Braintree backend. Carden prepares Braintree Level 2/3 fields from a QuickBooks invoice or an inline CanonicalInvoice v1. The merchant backend merges those fields into its own gateway.transaction.sale or gateway.transaction.submitForSettlement call, keeps its payment method nonces and gateway credentials, and reports outcomes.
From invoice facts to processor evidence
Each handoff is observable on its own; no earlier step substitutes for settlement evidence.
Prepare
Request Level 2/3 fields
Carden validates a linked QuickBooks invoice or an inline CanonicalInvoice v1 and returns Braintree fields.
Pay
Merge into your Braintree call
Your backend spreads the fields into transaction.sale or submitForSettlement with its own nonce and credentials.
Report
Report the outcome
Your backend reports the attempt with the preparation ID so Carden can correlate it.
Observe
Record signed Braintree webhooks
Carden verifies each webhook and records settlement status, refunds, disputes, and card classification.
| System | Responsibility |
|---|---|
| QuickBooks or inline input | Authoritative invoice, PO, item, quantity, unit, tax, shipping, and discount facts. |
| Carden | Validation, immutable preparation, Braintree Level 2/3 fields, merchant-reported outcomes, and signed webhook evidence. |
| Merchant backend | Braintree gateway credentials, payment method nonces, transaction.sale or submitForSettlement, and report delivery. |
| Braintree | Payment processing, settlement, refunds, disputes, and webhook notifications. |
What Carden records from Braintree
For each signed notification, Carden records the transaction's settlement status, refunds (credit transactions), and disputes. It also records the card classification Braintree returns (Commercial, Purchase, Corporate, Business, Debit, Prepaid, and Product ID), and whether the settled transaction retained a purchase order number, tax amount, and line items.
Current limits
| Area | Limit |
|---|---|
| Release stage | Preview. |
| Currency | Level 2/3 fields are prepared for USD transactions only. |
| Line items | Up to 249 line items per transaction. |
| Fees and interchange | Per-transaction fees and the interchange category are not available from webhooks. Transaction Level Fee Report import is planned for later. |
| Invoice scope | One fully unpaid invoice per transaction; the amount must equal the full invoice total. |
Savings vary by card product, network, merchant category, and the merchant's processor pricing. A lower interchange category only lowers merchant cost when the processor agreement passes it through.
Implement Braintree in order
Setup
Create a restricted API user, connect keys, add the webhook, and create a Carden key.
API reference
Prepare Level 2/3 fields, merge them into Braintree, and report outcomes.
Troubleshooting
Recover credential, webhook, and Level 2/3 preparation failures.
Savings evidence
Separate preparation and webhook evidence from verified savings.