Skip to main content

pesapal-python

A lightweight Python SDK for the Pesapal API v3, covering authentication, order submission, transaction status, refunds and cancellations, plus an optional Selenium helper to trigger the mobile-money STK push from the hosted payment page.

Features

  • Authenticate and transparently cache/refresh the bearer token.
  • Register IPN URLs and list them (needed to obtain a notification_id).
  • Submit orders and get back the redirect_url / order_tracking_id.
  • Initiate mobile money payment by driving the hosted iframe (optional).
  • Get transaction status for an order.
  • Refund completed transactions.
  • Cancel pending orders.

Installation

pip install pesapal-python

To use the Selenium mobile-money helper (requires Google Chrome + chromedriver):

pip install "pesapal-python[mobilemoney]"

Configuration via .env

Copy .env.example to .env and fill in your credentials:

PESAPAL_CONSUMER_KEY=xxx
PESAPAL_CONSUMER_SECRET=xxx=
PESAPAL_PRODUCTION_BASE_URL=https://pay.pesapal.com/v3
PESAPAL_SANDBOX_BASE_URL=https://cybqa.pesapal.com/pesapalv3

Then build the client straight from the environment:

from pesapal import PesapalClient

client = PesapalClient.from_env(sandbox=True)  # loads .env automatically

from_env reads PESAPAL_CONSUMER_KEY / PESAPAL_CONSUMER_SECRET and picks the base URL from PESAPAL_SANDBOX_BASE_URL or PESAPAL_PRODUCTION_BASE_URL depending on sandbox, falling back to the built-in defaults.

Quick start

from pesapal import PesapalClient, OrderRequest, BillingAddress

client = PesapalClient(
    consumer_key="YOUR_CONSUMER_KEY",
    consumer_secret="YOUR_CONSUMER_SECRET",
    sandbox=True,  # omit or set False for production
)

# 1. Authenticate (optional — called automatically on first request)
client.authenticate()

# 2. Register an IPN URL (once) to obtain a notification_id
ipn = client.register_ipn("https://your-app.com/ipn", "POST")
notification_id = ipn["ipn_id"]

# 3. Submit an order
order = OrderRequest(
    amount=1000,
    currency="UGX",
    description="Order #1234",
    callback_url="https://your-app.com/callback",
    notification_id=notification_id,
    branch="HQ",
    billing_address=BillingAddress(
        email_address="customer@example.com",
        phone_number="0775000000",
        country_code="UG",
        first_name="Jane",
        last_name="Doe",
    ),
)
submitted = client.submit_order(order)
order_tracking_id = submitted["order_tracking_id"]
redirect_url = submitted["redirect_url"]

# 4. Initiate mobile money (drives the hosted form; phone is prepopulated)
result = client.initiate_mobile_money_payment(redirect_url, headless=True)
print(result.success, result.tracking_id, result.response_id)

# 5. Check transaction status
status = client.get_transaction_status(order_tracking_id)
print(status["payment_status_description"])

# 6. Refund a completed transaction
client.refund(
    confirmation_code=status["confirmation_code"],
    amount=1000,
    username="Operator Name",
    remarks="Service not offered",
)

# 7. Cancel a pending order
client.cancel_order(order_tracking_id)

Environments

Environment Base URL
Production https://pay.pesapal.com/v3
Sandbox https://cybqa.pesapal.com/pesapalv3

Select with PesapalClient(..., sandbox=True) or pass a custom base_url.

Error handling

All API failures raise a subclass of PesapalError:

from pesapal import PesapalAPIError, PesapalAuthError

try:
    client.submit_order(order)
except PesapalAuthError as exc:
    ...  # bad credentials / token problem
except PesapalAPIError as exc:
    print(exc.status_code, exc.error, exc.response)

The mobile-money helper does not raise on failure; it returns a MobileMoneyResult with success=False and an error message.

License

MIT

Metadata

Release files for pesapal-python 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pesapal-python 1.0.0
File Size Uploaded Provenance Actions
pesapal_python-1.0.0.tar.gz 14.1 kB With provenance Details for pesapal_python-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pesapal-python 1.0.0
File Interpreter ABI Platform Actions
pesapal_python-1.0.0-py3-none-any.whl Python 3 none any Details for pesapal_python-1.0.0-py3-none-any.whl

Total release size: 26.1 kB

Release files / pesapal_python-1.0.0.tar.gz

Download URL pesapal_python-1.0.0.tar.gz
Size 14.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5cbd3d3b9cf38ad97701ebc6791f5f09933919e23ab81bdd9d962ced3ba8a683
BLAKE2b-256 checksum
How to use checksums
624b00a8b6efa7eb8fb78f6e93cd5d0a774b3441104e90fd35f6e211e3a43435
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 22, 2026.

Transparency log

Release files / pesapal_python-1.0.0-py3-none-any.whl

Download URL pesapal_python-1.0.0-py3-none-any.whl
Size 12.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8a9e9840286dcdaad204020ea6dde93a1ed8121eefdf2876b232b02cf23013f
BLAKE2b-256 checksum
How to use checksums
a334b238c23f0cbd23ef4e7e39e5f8b665b12622e1c960c14847c742602a9910
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 22, 2026.

Transparency log

Security for pesapal-python 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pesapal_python-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page