Payload Python Library

A Python library for integrating Payload.

Installation

Install using pip

pip install payload-api

Get Started

Once you've installed the Payload Python library to your environment, import the payload module to get started. Note: We recommend using the shorthand name of pl when importing.

import payload as pl

API Authentication

To authenticate with the Payload API, you'll need a live or test API key. API keys are accessible from within the Payload dashboard.

import payload as pl
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

Session based:

import payload
pl = payload.Session('secret_key_3bW9JMZtPVDOfFNzwRdfE')

API Versioning

The Payload API supports multiple versions. You can specify which version to use when making requests:

import payload as pl
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
pl.api_version = 'v2'  # Use API v2

Or with sessions:

import payload
pl = payload.Session(
    'secret_key_3bW9JMZtPVDOfFNzwRdfE',
    api_version='v2'
)

API v2 introduces new objects including Profile, Intent, Entity, Transfer, ProcessingAgreement, and more. See the Payload API Documentation for details on API versions.

Creating an Object

Interfacing with the Payload API is done primarily through Payload Objects. Below is an example of creating a customer using the pl.Customer object.

# Create a Customer
customer = pl.Customer.create(
	email='matt.perez@example.com',
	name='Matt Perez'
)

# Create a Payment
payment = pl.Payment.create(
    amount=100.0,
    payment_method=pl.Card(
        card_number='4242 4242 4242 4242',
        expiry='12/28',
        card_code='123'
    )
)

Accessing Object Attributes

Object attributes are accessible through dot notation.

customer.name

Updating an Object

Updating an object is a simple call to the update object method.

# Updating a customer's email
customer.update( email='matt.perez@newwork.com' )

Selecting Objects

Objects can be selected using any of their attributes.

# Select a customer by email
customers = pl.Customer.filter_by(
    email='matt.perez@example.com'
)

Use the pl.attr attribute helper interface to write powerful queries with a little extra syntax sugar.

payments = pl.Payment.filter_by(
    pl.attr.amount > 100,
    pl.attr.amount < 200,
    pl.attr.description.contains("Test"),
    pl.attr.created_at > datetime(2021,2,1)
).all()

Testing the Payload Python Library

Tests are contained within the tests/ directory. To run tests:

# Install dependencies
pdm install

# Run integration tests
TEST_SECRET_KEY=test_api_key pdm run pytest tests/int/

# Run unit tests
pdm run pytest tests/unit/

# Run a specific test file
TEST_SECRET_KEY=test_api_key pdm run pytest tests/int/test_transaction.py

Documentation

To get further information on Payload's Python library and API capabilities, visit the unabridged Payload Documentation.