Braintree troubleshooting
Recover Braintree credential, webhook, and Level 2/3 preparation failures without repeating a Braintree transaction.
On this page
Identify the failed stage
- Confirm the merchant, Carden environment, Braintree environment, and Carden key.
- Save the x-carden-request-id, preparation.id, attemptId, eventId, and Braintree transaction ID.
- Separate preparation, your Braintree sale or capture, your Carden report, and Braintree webhook delivery.
- Retry only the operation that failed. A Carden failure never justifies another Braintree sale.
Connect and verify keys
| Symptom | Recovery |
|---|---|
| Authentication failed | The keys belong to the other Braintree environment, or a value was copied incompletely. Use sandbox keys in a sandbox workspace and production keys in a production workspace. |
| Authorization failed | The API user's role cannot view transactions. Grant transaction view access to its custom role, then select Verify and connect again. |
| Merchant already connected | This Braintree merchant is connected to another Carden workspace. Disconnect it there, or connect the intended workspace. |
| Line item count shows — | The API user's role cannot read line items. Grant that view permission; Carden reads line items after a sale settles because webhooks omit them. |
Carden never shows the private key after saving. To change keys, generate a new key in Braintree and select Rotate API keys.
Fix webhook delivery
| Symptom | Recovery |
|---|---|
| Stays Awaiting first notification | The destination URL must be public HTTPS. Select Check URL next to the webhook in Braintree, then Refresh webhook status in Carden. For local development, expose your server through an HTTPS tunnel. |
| 400 invalid_signature | The keys were rotated or disconnected after the webhook was created. Save the current keys in Carden for the same Braintree merchant. |
| 400 invalid_event | The delivery is missing bt_signature or bt_payload, or the notification is incomplete. |
| 404 endpoint_not_found | The URL in Braintree does not match the destination URL in Carden. Copy it again. |
| 409 credentials_required / connection_unavailable | Connect Braintree keys in Carden, or reconnect a disconnected integration. |
| 410 endpoint_disabled | The integration was disconnected. Remove the old webhook in Braintree. |
Resolve Level 2/3 preparation issues
| Symptom | Recovery |
|---|---|
| missing_purchase_order_number | Add the buyer's PO to the invoice in QuickBooks. If your buyers use the invoice number as their reference, pass purchaseOrderNumberSource: "invoice_number" on inline requests. |
| purchase_order_number_too_long / identifier_too_long | Braintree limits PO numbers to 17 characters and codes and units to 12. Carden does not truncate identifiers; correct the source or take an ordinary payment. |
| missing_product_code / missing_unit_of_measure | Add the SKU or unit to the item in QuickBooks, or approve an evidence-backed item mapping. |
| unsupported_currency | Level 2/3 fields are prepared for USD only. Take the payment without Level 2/3 fields. |
| arithmetic_mismatch / payment_amount_mismatch | Correct the invoice amounts, and charge the full invoice total. |
- Carden never invents PO numbers, SKUs, units, quantities, or tax.
- For checkout readiness, a PO, SKU, or unit gap downgrades to an ordinary payment instead of blocking it.
- A Level 3 ineligible transaction can still settle normally; it just carries no Level 2/3 data.
Test a sandbox checkout
Authorized Carden operators can run a sandbox test checkout at /demo/braintree. It is not available to merchants.
- Use sandbox card 4111 1111 1111 1111 for an ordinary test.
- Use sandbox card 4111 1111 1113 1010 to get a commercial card indicator.
- Select Settle now to settle the sandbox transaction. Braintree then sends a real transaction_settled webhook to the configured destination URL.
Do not infer savings from webhook evidence
Braintree webhooks do not include per-transaction fees or the interchange category. A commercial card classification and a retained PO, tax amount, or line items show eligibility and transmission, not qualification. Verified savings need settlement cost evidence, pass-through pricing, and a documented baseline.