Skip to content

README.md

Latest commit

 

History

History
164 lines (125 loc) · 5.38 KB

README.md

File metadata and controls

164 lines (125 loc) · 5.38 KB
Raw

PayDunya Python SDK

CI Docs Python PyPI

Python client library for integrating PayDunya payment services — mobile money, card payments, and more for businesses across West Africa.

Features

  • PAR — Payment And Redirection: create invoices and redirect customers to PayDunya's payment page
  • PSR — Payment Without Redirection: server-side token generation for the JavaScript popup flow
  • PER — Payment And Redistribution (DirectPay): transfer funds to other PayDunya accounts
  • DMP — Payment Request API: send payment links to customers via SMS or Email
  • IPN — Instant Payment Notification hash verification helper
  • Pydantic v2 models with built-in validation (email format, amount bounds, required fields)
  • Fully typed, httpx-based transport, Python 3.10+

Installation

uv add paydunya
# or
pip install paydunya

Quick Start

from paydunya import Invoice, InvoiceItem, PaydunyaClient, Store

client = PaydunyaClient(
    master_key="wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW",
    private_key="test_private_rMIdJM3PLLhLjyArx9tF3VURAF5",
    token="IivOiOxGJuWhc5znlIiK",
    mode="test",
)

store = Store(name="Sandra's Store")
items = [
    InvoiceItem(
        name="Croco shoes",
        quantity=3,
        unit_price="10000",
        total_price="30000",
        description="Shoes made of genuine crocodile skin",
    ),
    InvoiceItem(
        name="Ice Shirt",
        quantity=1,
        unit_price="5000",
        total_price="5000",
    ),
]

invoice = Invoice(client, store)
invoice.add_items(items)
invoice.add_tax("TVA (18%)", 6300)
invoice.set_total_amount(42300)
invoice.set_description("Payment for items from Sandra's Store")
invoice.set_customer(name="John Doe", email="john@example.com", phone="771111111")
invoice.set_return_url("https://my-shop.com/thanks")
invoice.set_cancel_url("https://my-shop.com/cancelled")
invoice.set_callback_url("https://my-shop.com/ipn")

response = invoice.create()
print(response["response_text"])  # payment page URL

status = invoice.confirm(response["token"])
print(status["status"])  # pending, completed, cancelled, failed

DMP — Payment Requests via SMS/Email

from paydunya import DMP, PaydunyaClient

client = PaydunyaClient(
    master_key="...", private_key="...", token="...",
    mode="live",
)

dmp = DMP(client)

result = dmp.create(
    amount=5000,
    recipient_email="customer@example.com",
    support_fees=True,
    send_notification=False,
)
print(result["url"])  # payment link to include in your custom message
print(result["reference_number"])

status = dmp.check_status(result["reference_number"])
print(status["status"])  # pending, completed, failed

DirectPay (PER)

from paydunya import DirectPay, PaydunyaClient

client = PaydunyaClient(master_key="...", private_key="...", token="...")
dp = DirectPay(client)
response = dp.pay(account_alias="774563209", amount=215000)
print(response["transaction_id"])

IPN Verification

from paydunya import verify_ipn_hash

if verify_ipn_hash(
    master_key="your-master-key",
    received_hash=request.POST["data"]["hash"],
):
    status = request.POST["data"]["status"]

Sandbox Testing

PayDunya provides fictitious customer accounts to test without real money. See the Sandbox Testing guide in the docs or run the interactive example:

PAYDUNYA_MASTER_KEY="..." PAYDUNYA_PRIVATE_KEY="..." PAYDUNYA_TOKEN="..." \\
    python examples/sandbox_e2e.py

API Keys

Register at paydunya.com/integration-setups, create an application, and retrieve your three keys:

  • PAYDUNYA-MASTER-KEY — main application key
  • PAYDUNYA-PRIVATE-KEY — private key (test_private_... or live_private_...)
  • PAYDUNYA-TOKEN — application token

Use mode="test" for sandbox testing and mode="live" for production.

Migration from v1.x

The v2.0 API has been redesigned:

  • PaydunyaClient(master_key, private_key, token, mode="test") replaces the old paydunya.debug / paydunya.api_keys globals
  • OPR has been removed — use the PSR JavaScript flow documented at developers.paydunya.com
  • Invoice.confirm(token) is now a clear method
  • Items are now keyed item_0, item_1 (docs-compliant, formerly a flat array)
  • Pydantic v2 models replace plain dataclasses — input validation (email format, amount bounds, required fields) happens at the SDK boundary
  • Invoice.customer pre-fill via set_customer()

Development

uv sync --dev          # install all dependencies
uv run pytest          # run tests
uv run ruff check .    # lint
uv run tox             # test across Python 3.10–3.13
uv build               # build distribution packages

License

MIT — see LICENSE.txt