Braintree

Braintree is a self-serve connector built on three values: a merchant ID, a public key and a private key. What decides whether the connection is any good is the limited-access role you attach to the API user — get it wrong and whole domains arrive empty without an error.

What you get

Transactions with masked payment data, recurring-billing and subscription records, disputes, customer and payment-method records, verifications, and statement and report data. Field-level definitions live in Athia Data Dictionary.

Strongest for subscriptions. Braintree carries recurring-billing detail most card connectors do not, which makes it the reference source for renewal success and for involuntary churn from failed rebills.

Weakest where permissions are narrow. Coverage is a direct function of the role you grant; disputes and customers are the domains that most often go missing.

Before you start

In the Braintree console, create a limited-access role for Athia and assign it to the API user. The role needs:

• Transactions: Download Transactions with Masked Payment Data
• Reporting: Create, Run, and Download Reports; View Dashboard Graphs
• Recurring Billing: Download Subscription Records, View Modifications, View Subscription Plans, View Subscriptions, Search Subscriptions
• Dispute Management: View, manage, and contest disputes
• Webhooks: Manage Webhooks (Add/Edit/Delete)
• Statements: View Statements
• Read-Only Access: View Address, View Customers, View Merchant Accounts, View Payment Methods, View Transactions, View Verifications, Download Files
• Search: Search Transactions, Search Verifications

View Address and View Customers are the two most often left off. Without them the address and customer tables sync empty and no error is raised.

Then assign the API user to all merchant accounts — Braintree scopes access per merchant account, so an account left off contributes nothing.

Create the API user and keys

1. Log into the Braintree Control Panel as an admin and create the role above.
2. Create a new user, and enable API Access for that user.
3. Assign the limited-access role you created.
4. Select all merchant accounts.
5. Log out and log back in as that new user, then generate and copy the Merchant ID, Public Key and Private Key.

Credentials Athia asks for

Setting up the connection

1. Create the role, assign it to the API user, and assign that user to every merchant account.
2. In Settings → Connections, choose + Add Connection and select Braintree.
3. On Configure Connector, enter a Name and pick a Schedule.
4. On Enter Credentials, enter the Merchant Id, Public Key and Private Key.
5. Choose Verify Connection.

The connection then shows as ACTIVE and the first sync starts. Check that disputes and customers are actually populated — that is the fastest confirmation the role is right.

Register the Athia webhook in Braintree

Braintree pushes transaction, subscription and dispute updates to Athia in real time once the destination is registered.

1. In the connection wizard, copy the Athia Webhook Destination URL.
2. Log into the Braintree Control Panel as the limited-access user and create a webhook.
3. Paste the Athia URL into Destination URL.
4. Under Notifications, enable all notification event options.
5. Test and save, then enable the webhook.

Sync cadence

Pick a Schedule that matches how closely you monitor acceptance. Subscription and dispute records advance on Braintree's own billing and dispute cycles whatever you choose.

Limits and things to know

• Missing permissions produce empty domains, not errors. Without read rights, disputes and customers sync empty while verification still succeeds.
• Coverage follows merchant-account assignment. Accounts the API user is not assigned to are absent.
• Production and Sandbox are separate connections. Each environment issues its own merchant ID and key pair — create one connection per environment and never mix credentials between them.
• Settlement and disbursement fields lag up to two days behind the transaction. Read settlement figures on matured days, not on today's.
• Amounts are decimal — never divide by 100.
• Card data is minimized. The role above grants masked payment data only.

Troubleshooting

Related

Other providers and ingestion paths are listed in Athia Connectors. For file drops and warehouse-to-warehouse alternatives to a direct connector, see Integrating Athia.