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:
Merchant ID: Click ‘Business’ and find your Merchant ID at the top of this page.
Public API Key: Click ‘API’ and scroll to ‘API Keys’. If there are none, click ‘Generate New API Key’.
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