Braintree

Overview

Braintree is an online payment processor often integrated in other third-party donation platforms like ActionKit, etc. Even if much data is accessible through those other platforms things like credit card disputes and disbursement (to your bank account!) timing may only be available directly through Braintree.

While much of the Braintree API is about processing payments, this Parsons integration focuses on the record searching aspects. Specifically, the Braintree class provides methods for fetching disputes and transactions.

Note

Authentication

Braintree authentication requires a Merchant ID, Public Key, and Private Key. These can be obtained by logging in to the Braintree Control Panel, clicking on the gear icon in the top right corner, and finding each of the credentials as follows:

  1. Merchant ID: Click ‘Business’ and find your Merchant ID at the top of this page.

  2. Public API Key: Click ‘API’ and scroll to ‘API Keys’. If there are none, click ‘Generate New API Key’.

  3. Private API Key: Click ‘API’, scroll to ‘API Keys’, and click the ‘view’ link in the private column.

For more information, see the API documentation.

Quick Start

To instantiate the Braintree class, you can either store your Merchant ID, Public API Key, and Private API Key as environmental variables (BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY, and BRAINTREE_PRIVATE_KEY, respectively) or pass them in as arguments:

from parsons import Braintree

# First approach: Use API credentials via environmental variables
brains = Braintree()

# Second approach: Pass API credentials as arguments
brains = Braintree(merchant_id='my_merchant_id', public_key='my_public_key', private_key='my_private_key')

# Get disputes from a single day
disputes = brains.get_disputes('2020-01-01', '2020-01-02')

# Get disbursements from a single day
disbursements = brains.get_transactions(disbursement_start_date='2020-01-01',
                                        disbursement_end_date='2020-01-02')

API

class parsons.braintree.Braintree(merchant_id=None, public_key=None, private_key=None, timeout=None, production=True)[source]

Braintree is a payment processor. Args:

merchant_id: str

Braintree merchant id – probably a 16-char alphanumeric. Not required if BRAINTREE_MERCHANT_ID env variable is set.

public_key: str

Braintree public key – probably a (different) 16-char alphanumeric. Not required if BRAINTREE_PUBLIC_KEY env variable is set.

private_key: str

Braintree private key – probably a 32-char alphanumeric. Not required if BRAINTREE_PRIVATE_KEY env variable is set.

timeout: int

Optionally change the timeout from default of 200 seconds. Can also be passed with env var BRAINTREE_TIMEOUT.

production: bool

Defaults to True. If you are testing in a Sandbox, set this to False.

Returns:

Braintree class

get_disputes(start_date=None, end_date=None, query_list=None, query_dict=None)[source]

Get a table of disputes based on query parameters. There are three ways to pass query arguments: Pass a start_date and end_date together for a date range, or pass a query_list or query_dict argument.

Args:
start_date: date or str

Start date of the dispute range. Requires end_date arg. e.g. ‘2020-11-03’

end_date: date or str

End date of the dispute range. Requires start_date arg. e.g. ‘2020-11-03’

query_list: list of braintree.DisputeSearch

You can use the braintree.DisputeSearch to create a manual list of query parameters.

query_dict: jsonable-dict

query_dict is basically the same as query_list, except instead of using their API objects, you can pass it in pure dictionary form. Some examples:

# The start_date/end_date arguments are the same as
{"effective_date": {"between": [start_date, end_date]}}
# some other examples
{"merchant_account_id": {"in_list": [123, 456]}}
{"created_at": {"greater_than_or_equal": "2020-03-10"}}
Returns:

Table Class

get_subscriptions(table_of_ids=None, start_date=None, end_date=None, query_list=None, query_dict=None, include_transactions=False, just_ids=False)[source]

Get a table of subscriptions based on query parameters. There are three ways to pass query arguments: Pass a disbursement_start_date and disbursement_end_date together for a date range, or pass a query_list or query_dict argument.

Args:
start_date: date or str

Start date of the subscription range. Requires end_date arg. e.g. ‘2020-11-03’

end_date: date or str

End date of the subscription range. Requires start_date arg. e.g. ‘2020-11-03’

query_list: list of braintree.SubscriptionSearch

You can use the braintree.SubscriptionSearch to create a manual list of query parameters.

query_dict: jsonable-dict

query_dict is basically the same as query_list, except instead of using their API objects, you can pass it in pure dictionary form. Some examples:

# The start_date/end_date arguments are the same as
{"created_at": {"between": [start_date, end_date]}}
# some other examples
{"merchant_account_id": {"in_list": [123, 456]}}
{"created_at": {"greater_than_or_equal": "2020-03-10"}}
include_transactions: bool

If this is true, include the full collection of transaction objects. Otherwise, just return a list of transaction IDs.

just_ids: bool

While querying a list of subscription ids is a single, fast query to Braintree’s API, getting all data for each subscription is force-paginated at 50-records per request. If you just need a count or the list of ids, then set just_ids=True and it will return a single column with id instead of all table columns.

table_of_ids: Table with an id column – i.e. a table returned from just_ids=True

Subsequently, after calling this with just_ids, you can prune/alter the ids table and then pass the table back to get the full data. These are somewhat-niche use-cases, but occasionally crucial when a search result returns 1000s of ids.

Returns:

Table Class

get_transactions(table_of_ids=None, disbursement_start_date=None, disbursement_end_date=None, query_list=None, query_dict=None, just_ids=False)[source]

Get a table of transactions based on query parameters. There are three ways to pass query arguments: Pass a disbursement_start_date and disbursement_end_date together for a date range, or pass a query_list or query_dict argument.

Args:
disbursement_start_date: date or str

Start date of the disbursement range. Requires disbursement_end_date arg. e.g. ‘2020-11-03’

disbursement_end_date: date or str

End date of the disbursement range. Requires disbursement_start_date arg. e.g. ‘2020-11-03’

query_list: list of braintree.TransactionSearch

You can use the braintree.TransactionSearch to create a manual list of query parameters.

query_dict: jsonable-dict

query_dict is basically the same as query_list, except instead of using their API objects, you can pass it in pure dictionary form. Some examples:

# The disbursement_start_date/disbursement_end_date arguments are the same as
{"disbursement_date": {"between": [start_date, end_date]}}
# some other examples
{"merchant_account_id": {"in_list": [123, 456]}}
{"created_at": {"greater_than_or_equal": "2020-03-10"}}
just_ids: bool

While querying a list of transaction ids is a single, fast query to Braintree’s API, getting all data for each transaction is force-paginated at 50-records per request. If you just need a count or the list of ids, then set just_ids=True and it will return a single column with id instead of all table columns.

table_of_ids: Table with an id column – i.e. a table returned from just_ids=True

Subsequently, after calling this with just_ids, you can prune/alter the ids table and then pass the table back to get the full data. These are somewhat-niche use-cases, but occasionally crucial when a search result returns 1000s of ids.

Returns:

Table Class