payload-api 0.5.1
Payload Python Library
License: MIT
Requires Python: >=3.7

# Payload Python Library

A Python library for integrating [Payload](https://payload.com).

## Installation

### Install using pip

```bash
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.

```python
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.

```python
import payload as pl
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'
```

----------------------------

Session based:

```python
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:

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

Or with sessions:

```python
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](https://docs.payload.com) 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.


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


```python
# 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.

```python
customer.name
```

### Updating an Object

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

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

### Selecting Objects

Objects can be selected using any of their attributes.

```python
# 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.

```python
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:

```bash
# 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](https://docs.payload.com/?python).