> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Braintree

> Connect Braintree over two channels: the API for transaction and dispute data, and SFTP fee reports for detailed fee data.

This guide will help you connect Braintree settlement, payment, **and fee** data to your Payrails account. Payrails ingests Braintree data over two channels:

* **API** — transaction, payment, and dispute data (requires Braintree API credentials, below).
* **SFTP fee reports** — Braintree's **Disbursement Fee Report (DFR)** and **AIB Transaction Fee Report**, which carry detailed fee data the API does not expose. These require Braintree Dropzone (SFTP) credentials.

Providing both gives the most complete fee reporting in Payrails.

## Prerequisites

* A Braintree account with admin access.
* (For fee reports) A Braintree **Dropzone** provisioned for your account — the DFR is delivered for US/Fiserv-acquired accounts, the AIB report for EU-acquired accounts. If you're unsure whether your Dropzone is set up, ask your Braintree/Fiserv contact.

***

## Part A — API credentials

We recommend creating a limited-access set of API keys for Payrails reporting.

### Step 1: Log into the Braintree production environment as an admin

### Step 2: Create a new role

1. Follow the instructions in the Braintree documentation to create a new role.
2. Assign the following permissions to this new role under “Rights Granted“:
   * Transactions
   * Download Transactions with Masked Payment Data
   * Reporting
   * Create, Run, and Download Reports
   * View Dashboard Graphs
   * Read-only Access
   * View Merchant Accounts
   * View Payment Methods
   * View Transactions
   * View Verifications
   * Download Files
   * Statements
   * View statements
   * Search
   * Search Transactions
   * Search Verifications

### Step 3: Create a new user and generate API keys

1. Follow the Braintree documentation to create a new user, with the following configuration:
   * Enable API Access.
   * Assign the role created in Step 2.
   * Select all merchant accounts for which you would like to send data.
2. Log in with this new user and store the following credentials:
   * Public key
   * Private key

### Step 4: Add the Braintree integration in the Payrails portal (self-serve)

1. Log in to the Payrails dashboard and open **Settings → Integrations → Data**.
2. Click **Add instance** (top-right).
3. In New instance, select provider: **Braintree** and click **Continue**.
4. On the **Configure account** screen, fill in:
   * **Integration instance name** — a unique label.
   * **Start Date** — the date of today or tomorrow (currently we can not backfill over the sel-serve capability. In the need of backfilling, please reach out to your Payrails account manager).
   * **Is Live / environment** — select production.
   * **Public key** and **Private key** — from the reporting user created in Step 3.
   * **Merchant accounts** — add each merchant account you want to ingest data for.
   * *(Optional)* **Additional data**.
5. Click **Save account**. The instance appears in the Data integrations list and Payrails begins ingesting data.

***

## Part B — SFTP fee-report credentials (DFR + AIB)

The DFR and AIB reports are delivered to a Braintree **Dropzone** over SFTP. To let Payrails collect them, share your Dropzone credentials.

### Step 1: Confirm your Dropzone is provisioned

Confirm with your Braintree/Fiserv contact that your account has a Dropzone delivering the Disbursement Fee Report (US/Fiserv) and/or the AIB Transaction Fee Report (EU). These reports are scheduled deliveries — no action is needed in the Braintree Control Panel.

### Step 2: Obtain your Dropzone (SFTP) username and password

Your Dropzone uses **password-based SFTP** at `dropzone.braintreepayments.com`. You only need the **username** and **password** (the host and port are standard). If you've previously connected with a tool like Cyberduck or FileZilla, these are the same credentials.

### Step 3: Share the API credentials with Payrails

1. Share your API credentials securely with Payrails — use a shared secrets manager/vault (1Password Shared Vaults, AWS Secrets Manager, GCP Secret Manager).
2. If a shared vault isn't possible, share them via a PGP-encrypted file.

***

## What Payrails ingests, and the fee detail you unlock

With the API credentials, Payrails ingests your transactions, payment-level fees, and disputes. Adding the Dropzone fee reports additionally surfaces detailed **fee categories** in your Payrails fee reporting and dashboards, including:

* **Scheme (card-network) fees**, including scheme fees charged on declined transactions.
* **Cross-border / international fees.**
* **EU acquiring fees** (from the AIB report) — often the only source of this detail for EU-acquired volume.
* **Chargeback fees.**

These complement the interchange and processing fees already available via the API, giving a complete view of your Braintree cost of payments in Payrails.


## Related topics

- [Braintree (Paypal)](/docs/orchestration/integrations/braintree.md)
- [Connect your data sources](/docs/analytics-and-reporting/getting-started/connect-your-data-sources/index.md)
- [Integrations](/docs/orchestration/integrations/index.md)