PyPaystack2

https://gray-adeyi.github.io/pypaystack2/v3.3/
Admin
PyPaystack2 is a developer-friendly Python client library for integrating Paystack APIs into Python...
Tokens:884,549
Snippets:2,747
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### get_customers async method implementation

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/customer

Fetches customers from Paystack with optional pagination, date filters, and a custom pydantic model. The method builds query parameters for page, start date, and end date, appends them to the URL, and sends a GET request. It returns a Response containing a list of Customer objects or a custom PaystackDataModel if provided.

```python
async def get_customers(
    self,
    start_date: str | None = None,
    end_date: str | None = None,
    page: int = 1,
    pagination: int = 50,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[list[Customer]] | Response[PaystackDataModel]:
    """Fetches customers available on your integration.

    Args:
        start_date: A timestamp from which to start listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
        end_date: A timestamp at which to stop listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
        page: Specify exactly what page you want to retrieve. If not specified, we use a default value of 1.
        pagination: Specifies how many records you want to retrieve per page.
            If not specified we use a default value of 50.
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    query_params = [
        ("page", page),
        ("from", start_date),
        ("to", end_date),
    ]
    url = self._full_url(f"/customer/?perPage={pagination}")
    url = append_query_params(query_params, url)
    return await self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or Customer,
    )
```

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

### Run CLI with --help flag

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00

Command to display the Typer app's help output, showing available options like --install-completion and --show-completion.

```bash
python main.py --help

```

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

### export_disputes method implementation

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/disputes?q=

Defines the `export_disputes` method that exports disputes from the integration. It accepts start and end dates, pagination, page, transaction ID, status, and an optional alternate pydantic model class. The method constructs a URL with query parameters and sends a GET request, returning a `Response` object containing either `DisputeExportInfo` or the alternate model.

```python
def export_disputes(
    self,
    start_date: str,
    end_date: str,
    pagination: int = 50,
    page: int = 1,
    transaction: str | None = None,
    status: DisputeStatus | None = None,
    alternate_model_class: type[PaystackDataModel] | None = None,
) -> Response[DisputeExportInfo] | Response[PaystackDataModel]:
    """Export disputes available on your integration.

    Args:
        start_date: A timestamp from which to start listing dispute e.g. 2016-09-21
        end_date: A timestamp at which to stop listing dispute e.g. 2016-09-21
        pagination: Specifies how many records you want to retrieve per page.
            If not specified we use a default value of 50.
        page: Specifies exactly what dispute you want to page. If not specified we use a default value of 1.
        transaction: Transaction ID
        status: Any value from the DisputeStatus enum
        alternate_model_class: A pydantic model class to use instead of the
            default pydantic model used by the library to present the data in
            the `Response.data`. The default behaviour of the library is to
            set  `Response.data` to `None` if it fails to serialize the data
            returned from paystack with the model provided in the library.
            Providing a pydantic model class via this parameter overrides
            the library default model with the model class you provide.
            This can come in handy when the models in the library do not
            accurately represent the data returned, and you prefer working with the
            data as a pydantic model instead of as a dict of the response returned
            by  paystack before it is serialized with pydantic models, The original
            data can be accessed via `Response.raw`.

    Returns:
        A pydantic model containing the response gotten from paystack's server.
    """

    url = self._full_url(f"/dispute/export?perPage={pagination}")
    query_params = [
        ("page", page),
        ("from", start_date),
        ("to", end_date),
        ("transaction", transaction),
        ("status", status),
    ]
    url = append_query_params(query_params, url)
    return self._handle_request(  # type: ignore
        HTTPMethod.GET,
        url,
        response_data_model_class=alternate_model_class or DisputeExportInfo,
    )
```

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

### CLI help output showing available commands

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00?q=

Example output from running 'python main.py --help'. It shows the options and commands available, including new-customer, list-customers, get-customer, and update-customer.

```bash
$ python  main.py --help

 Usage: main.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                     │
│ --show-completion             Show completion for the current shell, to copy it or          │
│                               customize the installation.                                   │
│ --help                        Show this message and exit.                                   │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
│ new-customer                                                                                │
│ list-customers                                                                              │
│ get-customer                                                                                │
│ update-customer                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
```

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

### GET /refund/{reference}

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/refunds?q=

Gets details of a refund on your integration. This method is part of the RefundClient class and sends a GET request to the Paystack Refund API.

```APIDOC
## GET /refund/{reference}

### Description
Gets details of a refund on your integration.

### Method
GET

### Endpoint
/refund/{reference}

### Parameters
#### Path Parameters
- **reference** (string) - Required - The reference of the refund to retrieve.

### Request Example
GET /refund/REF123

### Response
#### Success Response (200)
- **data** (object) - The refund object, serialized into a pydantic model (default: Refund) or the provided alternate_model_class.
- **raw** (object) - The original response data from Paystack before serialization.

#### Response Example
{
  "data": {},
  "raw": {}
}
```

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

### Check CLI help with python main.py --help

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00?q=

Run this command to see the available commands and options for the CLI app. The output lists new-customer, list-customers, get-customer, and update-customer.

```bash
python main.py --help
```

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

### Get SubAccount: GET /subaccount/{id_or_code}

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/subaccounts

Retrieves a single subaccount by its ID or code. Constructs the URL with the provided id_or_code and sends a GET request using _handle_request.

```python
url = self._full_url(f"/subaccount/{id_or_code}")
return self._handle_request(  # type: ignore
    HTTPMethod.GET,
    url,
    response_data_model_class=alternate_model_class or SubAccount,
)
```

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

### create(name, description, price, currency, unlimited=None, quantity=None, alternate_model_class=None) async

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/products

Creates a new product on your integration. This method is asynchronous and returns a response containing the created product details.

```APIDOC
## create(name, description, price, currency, unlimited=None, quantity=None, alternate_model_class=None) async

### Description
Creates a new product on your integration.

### Method
POST

### Endpoint
/product

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Required - A description of the product.
- **price** (number) - Required - The price of the product.
- **currency** (string) - Required - The currency code (e.g., NGN, USD).
- **unlimited** (boolean) - Optional - Whether the product has unlimited quantity.
- **quantity** (integer) - Optional - The quantity of the product.
- **alternate_model_class** (type[PaystackDataModel] | None) - Optional - A pydantic model class to use instead of the default.

### Request Example
{
  "name": "Product Name",
  "description": "Product description",
  "price": 1000,
  "currency": "NGN",
  "unlimited": false,
  "quantity": 10
}

### Response
#### Success Response (200)
- **data** (object) - The created product object.
- **status** (boolean) - Indicates if the request was successful.

#### Response Example
{
  "status": true,
  "message": "Product created",
  "data": {
    "id": 123,
    "name": "Product Name",
    "description": "Product description",
    "price": 1000,
    "currency": "NGN"
  }
}
```

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

### Initialize project with uv

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00

Initializes a new project named 'paystack-cli-client' and changes into its directory. The command creates a default project structure with main.py, pyproject.toml, and README.md, and initializes a git repository.

```bash
uv init paystack-cli-client && cd paystack-cli-client

```

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

### GET /address_verification/states

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/miscellaneous?q=

Get a list of states for a country for address verification.

```APIDOC
## GET /address_verification/states

### Description
Get a list of states for a country for address verification.

### Method
GET

### Endpoint
/address_verification/states

### Parameters
#### Query Parameters
- **country** (string) - Required - The country to get states for. Accepts a value from the Country enum.

### Response
#### Success Response (200)
- **data** (array) - List of states.

#### Response Example
{
  "data": []
}
```

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

### CLI help output

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00

Shows the help output listing the available commands: new-customer, list-customers, get-customer, and update-customer.

```text
$ python  main.py --help

 Usage: main.py [OPTIONS] COMMAND [ARGS]...

╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                     │
│ --show-completion             Show completion for the current shell, to copy it or          │
│                               customize the installation.                                   │
│ --help                        Show this message and exit.                                   │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
│ new-customer                                                                                │
│ list-customers                                                                              │
│ get-customer                                                                                │
│ update-customer                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────╯

```

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

### GET /country

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/miscellaneous?q=

Gets a list of countries that Paystack currently supports.

```APIDOC
## GET /country

### Description
Gets a list of countries that Paystack currently supports.

### Method
GET

### Endpoint
/country

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - List of supported countries.

#### Response Example
{
  "data": []
}
```

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

### Minimal Typer app with new_customer command

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00

Initial setup for a Typer CLI app. Defines a new_customer command that prints a success message. Run with 'python main.py --help' to see the help output.

```python
# paystack-cli-client/main.py
from dotenv import load_dotenv
from typer import Typer

load_dotenv()

app = Typer()


@app.command()
def new_customer():
    print("new customer successfully created!")


if __name__ == "__main__":
    app()

```

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

### GET /split/{id_or_code}

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/splits?q=

Get details of a split on your integration by its ID or code.

```APIDOC
## GET /split/{id_or_code}

### Description
Get details of a split on your integration.

### Method
GET

### Endpoint
/split/{id_or_code}

### Parameters
#### Path Parameters
- **id_or_code** (string) - Required - The id or code of the split

### Response
#### Success Response (200)
- **data** (object) - TransactionSplit object

#### Response Example
{
  "data": {
    "id": 1,
    "name": "Split 1",
    "active": true
  }
}
```

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

### create(customer, plan, authorization=None, start_date=None, alternate_model_class=None)

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/subscriptions?q=

Creates a subscription on your integration. This method sends a POST request to the /subscription endpoint with the customer and plan details, and optionally sets the authorization and start date for the subscription.

```APIDOC
## create(customer, plan, authorization=None, start_date=None, alternate_model_class=None)

### Description
Creates a subscription on your integration. Paystack creates an email token on each subscription to allow customers to cancel their subscriptions from within the invoices sent to their mailboxes. Since they are not authorized, the email tokens are what we use to authenticate the requests over the API.

### Method
POST

### Endpoint
/subscription

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **customer** (int | str) - Required - Customer's email address or customer code
- **plan** (str) - Required - Plan code
- **authorization** (str | None) - Optional - If customer has multiple authorizations, you can set the desired authorization you wish to use for this subscription here. If this is not supplied, the customer's most recent authorization would be used
- **start_date** (str | None) - Optional - Set the date for the first debit. (ISO 8601 format) e.g. 2017-05-16T00:30:13+01:00
- **alternate_model_class** (type[PaystackDataModel] | None) - Optional - A pydantic model class to use instead of the default pydantic model used by the library to present the data in the `Response.data`. The default behaviour of the library is to set `Response.data` to `None` if it fails to serialize the data returned from paystack with the model provided in the library. Providing a pydantic model class via this parameter overrides the library default model with the model class you provide. This can come in handy when the models in the library do not accurately represent the data returned, and you prefer working with the data as a pydantic model instead of as a dict of the response returned by paystack before it is serialized with pydantic models, The original data can be accessed via `Response.raw`.

### Request Example
```json
{
  "customer": "customer@example.com",
  "plan": "PLN_xxxxxxxxxxxx",
  "authorization": "AUTH_xxxxxxxxxxxx",
  "start_date": "2017-05-16T00:30:13+01:00"
}
```

### Response
#### Success Response (200)
- **data** (Subscription | PaystackDataModel) - The subscription data, either as the default model or the alternate model class if provided.
- **status** (bool) - Indicates if the request was successful.
- **message** (string) - A message describing the result.

#### Response Example
```json
{
  "status": true,
  "message": "Subscription created",
  "data": {
    "customer": 123,
    "plan": 456,
    "authorization": "AUTH_xxxxxxxxxxxx",
    "start_date": "2017-05-16T00:30:13+01:00"
  }
}
```
```

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

### Resolve card BIN with GET request

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/verification

Sends a GET request to the /decision/bin/{bin_} endpoint to get card information. The method returns a pydantic model, using an alternate model class if provided.

```python
url = self._full_url(f"/decision/bin/{bin_}")
return self._handle_request(  # type: ignore
    HTTPMethod.GET,
    url,
    response_data_model_class=alternate_model_class or CardBin,
)
```

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

### Install pypaystack2 with pip or uv

Source: https://gray-adeyi.github.io/pypaystack2

Install the pypaystack2 package using pip or uv. For webhook CLI support, install the optional 'webhook' extra. Use the -U flag to upgrade to the latest version.

```bash
$ pip install -U pypaystack2
# or install with uv
$ uv add pypaystack2
# For webhook cli
$ pip install -U "pypaystack2[webhook]"
or install with uv
$ uv add "pypaystack2[webhook]"
```

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

### Initialize PaystackClient and make API calls

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference

Shows how to create a PaystackClient, assuming the secret key is set in the environment variable PAYSTACK_SECRET_KEY, or by passing it explicitly. It demonstrates initializing a transaction and fetching banks.

```python
from pypaystack2 import PaystackClient
from pypaystack2.enums import Country

client = PaystackClient() # Assumes your secret key is set in your environmental variables
# as PAYSTACK_SECRET_KEY. you may also choose to pass the secret key explicitly on instantiation
# of the client. `client = PaystackClient(secret_key='<your-secret-key>')`

# Initializing a transaction
response = client.transactions.initialize(amount=10_000,email="johndoe@example.com")
print(repr(response))

# Get banks
response = client.miscellaneous.get_banks(country=Country.NIGERIA)
print(repr(response))

```

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

### Get SubAccounts: GET /subaccount

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/subaccounts

Fetches a list of subaccounts. Builds a URL with pagination parameters (perPage) and query parameters (from, to, page). Uses append_query_params to add query parameters and _handle_request to send the GET request.

```python
url = self._full_url(f"/subaccount?perPage={pagination}")
query_params = [
    ("from", start_date),
    ("to", end_date),
    ("page", page),
]
url = append_query_params(query_params, url)
return self._handle_request(  # type: ignore
    HTTPMethod.GET,
    url,
    response_data_model_class=alternate_model_class or SubAccount,
)
```

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

### Create customer with optional first and last name flags

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/tutorials/tutorial-00

Alternative command to create a customer with a first name and last name using the --first-name and --last-name flags.

```bash
python main.py johndoe@example.com --first-name John --last-name Doe
```

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

### GET /dedicated_account/{dedicated_account_id}

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/dedicated_accounts

Get details of a dedicated virtual account on your integration. This method is available on the DedicatedAccountClient.

```APIDOC
## GET /dedicated_account/{dedicated_account_id}

### Description
Get details of a dedicated virtual account on your integration. This method is available on the DedicatedAccountClient.

### Method
GET

### Endpoint
/dedicated_account/{dedicated_account_id}

### Parameters
#### Path Parameters
- **dedicated_account_id** (integer or string) - Required - ID of dedicated virtual account

### Request Example
GET /dedicated_account/123

### Response
#### Success Response (200)
- **data** (DedicatedAccount or PaystackDataModel) - The response data, serialized to the default model or the provided `alternate_model_class`.
- **raw** (object) - The original response data before serialization.

#### Response Example
{
  "data": {
    "id": 123,
    "account_number": "0123456789",
    "bank": {
      "name": "Wema Bank",
      "slug": "wema-bank"
    }
  },
  "raw": {}
}
```

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

### initiate method implementation

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/bulk_charges?q=

Method to initiate a bulk charge. Takes a list of BulkChargeInstruction and an optional alternate model class. Returns a response model. The code shows the URL construction, payload serialization, and request handling.

```python
    url = self._full_url("/bulkcharge")
    payload = [item.model_dump() for item in body]
    return self._handle_request(  # type: ignore
        HTTPMethod.POST,
        url,
        payload,
        response_data_model_class=alternate_model_class or BulkCharge,
    )
```

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

### GET /plan/{id_or_code} - Get Plan

Source: https://gray-adeyi.github.io/pypaystack2/v3.3/reference/plans?q=

Fetches details of a specific plan on your integration using its ID or code.

```APIDOC
## [GET] /plan/{id_or_code}

### Description
Fetches details of a specific plan on your integration using its ID or code.

### Method
GET

### Endpoint
/plan/{id_or_code}

### Parameters
#### Path Parameters
- **id_or_code** (string|integer) - Required - The plan ID or code you want to fetch

### Request Example
GET /plan/PLN_abc123

### Response
#### Success Response (200)
- **data** (object) - The response data, serialized into a pydantic model (default: Plan) or the provided alternate_model_class.
- **raw** (object) - The original response data from Paystack before serialization.

#### Response Example
{
  "data": {},
  "raw": {}
}
```
Tokens:
Raw