Braintree

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.