PyPaystack2

PyPaystack2 is an Open Source Python client library for integrating Paystack into your python projects. It aims at being developer friendly and easy to use.

Version 3 is here now

Features

• 1st class support for type annotations.
• Synchronous and Asynchronous clients.
• Pydantic for data modelling.
• Fees Calculation utilities.
• Webhook support & utilities (>= v3.1.0).

Installation

$ 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]"

Usage Preview

In the REPL session below, we're using PyPaystack2 to create a Customer (user) and a Plan on Paystack and then add the newly created customer as a subscriber to the plan.

Note

The REPL session below assumes the environmental variable PAYSTACK_SECRET_KEY="YOUR_SECRET_KEY" is set. if not, you can alternatively pass it into the PaystackClient on instantiation like so PaystackClient(secret_key='YOUR_SECRET_KEY') otherwise, you will get a MissingSecretKeyException raised prompting you to provide a secret key. It also does not handle likely exceptions that calling client methods like client.customers.create, client.plans.create & client.subscriptions.create may raise like ClientNetworkError for network related issues and ValueError for validation related issues.

Python 3.11.13 (main, Sep  2 2025, 14:20:25) [Clang 20.1.4 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from pypaystack2 import __version__
>>> print(__version__)
3.0.0 # Ensure you're running PyPaystack2 version >= 3.0.0 for the following entries to work
>>> from pypaystack2 import PaystackClient
>>> from pypaystack2.enums import Interval
>>> from pypaystack2.models import Customer, Plan
>>> client = PaystackClient()
>>> new_customer_response = client.customers.create(email="johndoe@example.com",first_name="John",last_name="Doe")
>>> assert new_customer_response.status # Validating the request is successful
>>> new_customer = new_customer_response.data
>>> assert isinstance(new_customer,Customer) # Showing that we indeed get an instance of a pydantic model name `Customer` a modelled representation of the data returned by paystack as a result of the request to create a new user
>>> new_plan_response = client.plans.create(name="Test 1k Daily Contributions", amount=client.to_subunit(1000), interval=Interval.DAILY)
>>> assert new_plan_response.status # Validating the request is successful
>>> new_plan = new_plan_response.data # Validating the request is successful
>>> assert isinstance(new_plan,Plan)
>>> new_subscription_response = client.subscriptions.create(customer=new_customer.customer_code,plan=new_plan.plan_code)
>>> assert new_subscription_response.status == True # Validating the request is successful
>>> print(repr(new_subscription_response))
Response(
  status_code=<HTTPStatus.OK: 200>,
  status=True,
  message='Subscription successfully created',
  data=Subscription(
    customer=87934333,
    plan=2237384,...

Webhook

PyPaystack2 now supports verifying the authenticity of a webhook payload and a CLI to make working with webhooks locally seamless

Verifying a webhook payload

Python 3.11.13 (main, Sep  2 2025, 14:20:25) [Clang 20.1.4 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from pypaystack2 import PaystackClient
>>> client = PaystackClient()
>>> payload = ... # webhook payload e.g., b'{"event": "customeridentification.success", "data": {"customer_id": 324345768, "customer_code": "CUS_e7urjebaoyk1ze2", "email": "jddae8446e-e54c-42ab-bf37-e5abff14527e@example.com", "identification": {"country": "NG", "type": "bank_account", "bvn": "123*****543", "account_number": "342****22", "bank_code": "121"}}}'
>>> signature = ... # x-paystack-signature e.g., "5d049eb93c7c71fa098f5215d7297bda401710b62df8b392b9052adf8d1a02ff308f6ca57a1db14ffeabd5b66264e9c42de029b7067b9c71eb9c231fb2a8e383"
>>> is_verified_webhook_payload = client.is_verified_webhook_payload(payload,signature)
>>> print(is_verified_webhook_payload)
True

Forward webhook events from paystack to your app running locally

Note: This requires that you install pypaystack2[webhook]

pypaystack2 webhook start-tunnel-server --addr localhost:8000 --ngrok-auth-token

Documentation

See Documentation for more on this package.

Disclaimer

This project is an Open Source client library for Paystack. It is not officially endorsed or affiliated with Paystack. All trademarks and company names belong to their respective owners.

Contributions

Thank you for being interested in contributing to PyPaystack2. There are many ways you can contribute to the project:

• Star on GitHub
• Try PyPaystack2 and report bugs/issues you find
• Buy me a coffee

Other Related Projects