Paypal Braintree

Braintree is the PayPal enterprise payment solution

Omnata's PayPal Braintree plugin replicates transaction, subscription, dispute, and customer data from your Braintree merchant account into Snowflake, with both full-refresh and incremental sync strategies.

Prerequisites

To connect Braintree to Omnata, you need:

• An active Braintree merchant account (Sandbox or Production)

• A set of API credentials — Merchant ID, Public Key, and Private Key — generated from the Braintree control panel

Follow the Braintree control panel docs to create a new key set.

Authentication

API Keys

You connect Omnata to Braintree using your Merchant ID together with a public/private API key pair. The private key is treated as a Snowflake secret.

The following fields are required to create a connection in the Omnata UI:

Field	Required	Description
Merchant ID	Yes	Your Braintree Merchant ID.
Public Key	Yes	Your Braintree Public Key.
Private Key	Yes	Your Braintree Private Key. Stored as a Snowflake secret.
Environment	Yes	Either sandbox (for testing) or production (for live transactions).

Inbound Syncs

Objects are fetched incrementally wherever a usable cursor is available; otherwise the plugin falls back to full refresh.

The plugin exposes the following streams:

Stream	Primary Key	Cursor Field	Sync Strategies
transactions	id	created_at	Full Refresh, Incremental
subscriptions	id	created_at	Full Refresh, Incremental
customers	id	created_at	Full Refresh, Incremental
disputes	id	receivedDate	Full Refresh, Incremental

For the underlying object definitions and field reference, see the Braintree object reference.

Incremental sync — important caveats

Braintree's APIs constrain what "incremental" can capture. These caveats are inherent to the Braintree platform, not plugin design choices.

1. Updates to existing records are not captured

For transactions, subscriptions, and customers, the plugin queries Braintree's REST API with a created_at date range. Because created_at is immutable, an incremental run only returns records that were created since the last cursor. As such, updates to existing records are not returned

Although the records have an updated_at field, Braintree's search API does not support querying by updated_at, so the plugin cannot use it as a cursor.

Recommendation: Pair your incremental sync with a periodic Full Refresh + Replace (e.g. nightly or weekly, depending on tolerance) to pick up status changes. Filter on the latest snapshot downstream.

2. Disputes use a date-only cursor

The disputes stream cursor is receivedDate, which Braintree exposes at day precision only. The plugin filters with receivedDate >= since.date(), which means each incremental run re-fetches the entire current day to avoid missing late-arriving records.

Recommendation: Same as above, pair incremental with a periodic Full Refresh if dispute outcome tracking matters to you.

How the plugin handles deletes

Braintree's data model is largely append-only or state-based, so most "deletes" are actually status transitions rather than physical removals:

Object	Lifecycle
Transactions	Immutable once created. Refunds, voids and chargebacks appear as new transactions or as status changes (voided, submitted_for_settlement, settled, etc.). Transactions are not hard-deleted via the API.
Subscriptions	Cancellation is a status change (canceled), not a deletion. The subscription record remains in the API and continues to be returned.
Disputes	Records of historical events. Cannot be deleted.
Customers	Can be hard-deleted by an admin via the API. The customer no longer appears in Customer.search results after deletion.

Recommendations

Pattern	When to use
Filter on status downstream	For transactions, subscriptions and disputes, treat the status field as the lifecycle signal rather than expecting deletions. A cancelled subscription is still in the data — filter it out at the model level.
Periodic Full Refresh + Replace for customers	The only way to remove hard-deleted customers from Snowflake. Schedule alongside your incremental runs at a lower frequency (e.g. weekly) to reconcile.

Managing performance

The PayPal Braintree plugin exposes the following tuning parameters under the Tuning section of the inbound sync configuration. These can be changed without triggering change management workflows.

Parameter	Default	Description
Parallel fetch workers	1	Number of parallel API workers per stream. Increase to speed up large syncs at the cost of UDF memory.
Records per upload	500	Records buffered before each upload to Snowflake. Lower values reduce peak UDF memory; higher values reduce per-upload overhead.

Network addresses

The plugin requires outbound access to Braintree's API endpoints from Snowflake:

• api.braintreegateway.com — production API

• api.sandbox.braintreegateway.com — sandbox API

• payments.braintree-api.com — production payments

• payments.sandbox.braintree-api.com — sandbox payments

Outbound Syncs

Outbound syncs to Braintree are not currently supported. Contact us if this is a use case you'd like to discuss.