### 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='')` # 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": {} } ```