pybutton

This module is a thin client for interacting with Button’s API.

Please see the full API Docs for more information. For help, check out our Support page or get in touch.

Supported runtimes

cPython 2.7, 3.4, 3.5, 3.6, 3.7

Dependencies

None

Usage

pip install pybutton

To create a client capable of making network requests, instantiate a pybutton.Client with your API key.

from pybutton import Client

client = Client('sk-XXX')

The client will always attempt to raise a pybutton.ButtonClientError or a subclass in an error condition.

All API requests will return a pybutton.response.Response instance, which supports accessing data via the #data method. For instance:

from pybutton import Client
from pybutton import ButtonClientError, HTTPResponseError

client = Client("sk-XXX")

try:
    response = client.orders.get("btnorder-XXX")
except HTTPResponseError as e:
    print('API request failed: http status {}'.format(e.status_code))
except ButtonClientError as e:
    print(e)
else:
    print(response)
    # <class pybutton.Response status: open, btn_ref: None, line_items: [], ...>

    print(response.data())
    # {'status': open, 'btn_ref': None, 'line_items': [], ...}

Configuration

You may optionally supply a config argument with your API key:

from pybutton import Client

client = Client("sk-XXX", {
  'hostname': 'api.testsite.com',
  'port': 80,
  'secure': False,
  'timeout': 5, # seconds
})

The supported options are as follows:

hostname: Defaults to api.usebutton.com.
port: Defaults to 443 if config.secure, else defaults to 80.
secure: Whether or not to use HTTPS. Defaults to True. N.B: Button’s API is only exposed through HTTPS. This option is provided purely as a convenience for testing and development.
timeout: The time in seconds that may elapse before network requests abort. Defaults to None.

Resources

We currently expose the following resources to manage:

Accounts
Merchants
Orders
Customers
Links
Transactions

Accounts

All

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.all()

print(response)
# <class pybutton.Response [2 elements]>

Transactions (per-account)

Along with the required account ID, you may also pass the following optional arguments:

cursor (string): An API cursor to fetch a specific set of results.
start (ISO-8601 datetime string): Fetch transactions after this time.
end (ISO-8601 datetime string): Fetch transactions before this time.
time_field (string): Which time field start and end filter on.

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.transactions(
    'acc-123',
    start='2016-07-15T00:00:00.000Z',
    end='2016-09-30T00:00:00.000Z'
)

print(response)
# <class pybutton.Response [100 elements]>

Merchants

All

You may pass the following optional arguments:

status (string): Partnership status to filter by. One of (‘approved’, ‘pending’, or ‘available’)
currency (ISO-4217 string): Currency code to filter returned rates by

from pybutton import Client

client = Client('sk-XXX')

response = client.merchants.all()

print(response)
# <class pybutton.Response [23 elements]>

Orders

n.b: all currency values should be reported in the smallest possible unit of that denomination, i.e. $1.00 should be reported as 100 (i.e. 100 pennies)

Create

import hashlib
from pybutton import Client

client = Client('sk-XXX')

hashed_email = hashlib.sha256('user@example.com'.lower().strip()).hexdigest()

response = client.orders.create({
    'total': 50,
    'currency': 'USD',
    'order_id': '2007',
    'purchase_date': '2017-07-25T08:23:52Z',
    'finalization_date': '2017-08-02T19:26:08Z',
    'btn_ref': 'srctok-XXX',
    'customer': {
        'id': 'mycustomer-1234',
        'email_sha256': hashed_email,
    },
})

print(response)
# <class pybutton.Response total: 50, currency: 'USD', ...>

Get

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.get('btnorder-XXX')

print(response)
# <class pybutton.Response total: 50, currency: 'USD', ...>

Update

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.update('btnorder-XXX', {
    'total': 60,
})

print(response)
# <class pybutton.Response total: 60, currency: 'USD', ...>

Delete

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.delete('btnorder-XXX')

print(response)
# <class pybutton.Response >

Links

Create

from pybutton import Client

client = Client('sk-XXX')

response = client.links.create({
    'url': 'https://www.jet.com',
    "experience": {
        'btn_pub_ref': 'my-pub-ref',
        'btn_pub_user': 'user-id',
    },
})

print(response)
# <class pybutton.Response merchant_id: org-XXXXXXXXXXXXXXX, ...>

Get Info

from pybutton import Client

client = Client('sk-XXX')

response = client.links.get_info({
    "url": "https://www.jet.com",
})

print(response)
# <class pybutton.Response merchant_id: org-XXXXXXXXXXXXXXX, ...>

Customers

Create

import hashlib
from pybutton import Client

client = Client('sk-XXX')

hashed_email = hashlib.sha256('user@example.com'.lower().strip()).hexdigest()

response = client.customers.create({
    'id': 'customer-1234',
    'email_sha256': hashed_email,
})

print(response)
# <class pybutton.Response id: customer-1234, ...>

Get

from pybutton import Client

client = Client('sk-XXX')

response = client.customers.get('customer-1234')

print(response)
# <class pybutton.Response id: customer-1234, ...>

Transactions

All

You may pass the following optional arguments:

cursor (string): An API cursor to fetch a specific set of results.
start (ISO-8601 datetime string): Fetch transactions after this time.
end (ISO-8601 datetime string): Fetch transactions before this time.
time_field (string): Which time field start and end filter on.

from pybutton import Client

client = Client('sk-XXX')

response = client.transactions(
    start='2016-07-15T00:00:00.000Z',
    end='2016-09-30T00:00:00.000Z',
    time_field='modified_date',
)

print(response)
# <class pybutton.Response [100 elements]>

Response

Methods

data

from pybutton import Client

client = Client('sk-XXX')

response = client.orders.get('btnorder-XXX')

print(response.data())
# {'total': 50, 'currency': 'USD', 'status': 'open' ... }

response = client.accounts.all()

print(response.data())
# [{'id': 'acc-123', ... }, {'id': 'acc-234', ... }]

next_cursor

For any paged resource, next_cursor() will return a cursor to supply for the next page of results. If next_cursor() returns None, there are no more results.

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.transactions('acc-123')
cursor = response.next_cursor()

# loop through and print all transactions
while cursor:
    response = client.accounts.transactions('acc-123', cursor=cursor)
    print(response.data())
    cursor = response.next_cursor()

prev_cursor

For any paged resource, prev_cursor() will return a cursor to supply for the next page of results. If prev_cursor() returns None, there are no more previous results.

from pybutton import Client

client = Client('sk-XXX')

response = client.accounts.transactions('acc-123', cursor='xyz')

print(response)
# <class pybutton.Response [25 elements]>

cursor = response.prev_cursor()

response = client.accounts.transactions('acc-123', cursor=cursor)

print(response)
# <class pybutton.Response [100 elements]>

Utils

Utils houses generic helpers useful in a Button Integration.

#is_webhook_authentic

Used to verify that requests sent to a webhook endpoint are from Button and that their payload can be trusted. Returns True if a webhook request body matches the sent signature and False otherwise. See Webhook Security for more details.

import os

from pybutton.utils import is_webhook_authentic

is_webhook_authentic(
    os.environ['WEBHOOK_SECRET'],
    request.data,
    request.headers.get('X-Button-Signature')
)

Contributing

Building the egg: python setup.py bdist_egg
Building the wheel: python setup.py bdist_wheel --universal
Building the sdist: python setup.py sdist
Installing locally: python setup.py install
Running tests: python setup.py test (you’ll need to pip install flake8==3.3.0)
Running lint directly: flake8 pybutton
Running tests on all versions: tox (need to pip install tox and something like pyenv local 2.7.10 3.4.6 3.5.3 3.6.0 if using pyenv)

Release files for pybutton 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pybutton 3.0.0
File	Size	Uploaded
pybutton-3.0.0.tar.gz	14.3 kB	Sep 25, 2019	Details

Built distribution (wheel)

Table of built distributions (wheels) for pybutton 3.0.0
File	Interpreter	ABI	Platform	Reset
pybutton-3.0.0-py2.py3-none-any.whl 17.0 kB Sep 25, 2019	Python 2, Python 3	none	any	Details

Total release size: 31.2 kB

Release files / pybutton-3.0.0.tar.gz

Download URL	pybutton-3.0.0.tar.gz
Size	14.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`beb5ec3093d538c683c581ff60bb002de57c435269828ec7a3f926c21918f67e`
BLAKE2b-256 checksum How to use checksums	`66605f99534841b44712d0db5606fedd661c1892315182521794da2b4e525050`
Upload date	Sep 25, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.15.0 pkginfo/1.5.0.1 requests/2.9.1 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/2.7.10`

Release files / pybutton-3.0.0-py2.py3-none-any.whl

Download URL	pybutton-3.0.0-py2.py3-none-any.whl
Size	17.0 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`a463673ab958c1fe5fae4190a59ca75abe3d5c13f68caf9450e37e0d9c92ce26`
BLAKE2b-256 checksum How to use checksums	`1314edca40d1dabd40ac4ab9537f76c00cd32fa6483290393d33490fc0832146`
Upload date	Sep 25, 2019
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.15.0 pkginfo/1.5.0.1 requests/2.9.1 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/2.7.10`