CtechPay Python SDK

Official Python SDK for integrating CtechPay payments in Python applications.

Use this package from your server. Your CtechPay service token must never be exposed in browser JavaScript, mobile apps, or public repositories.

Installation

pip install ctechpay

Basic Usage

from ctechpay import CtechPay

ctechpay = CtechPay.client("YOUR_SERVICE_TOKEN")

You can also configure the API base URL and request timeout:

ctechpay = CtechPay.client(
    "YOUR_SERVICE_TOKEN",
    base_url="https://new-api.ctechpay.com",
    timeout=30,
)

Hosted Payment Page

Hosted checkout is the recommended integration for most merchants. CtechPay gives you a secure payment page where the customer can choose Airtel Money or card.

payment = ctechpay.hosted_payments.create({
    "amount": 100,
    "category_flag": "LOAN_APPLICATION",
    "customer_reference": "INV-1001",
    "customer_message": "Invoice payment",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "redirectUrl": "https://example.com/payments/success",
    "cancelUrl": "https://example.com/payments/cancelled",
})

print(payment["data"]["hosted_payment_url"])

Redirect your customer to payment["data"]["hosted_payment_url"].

Hosted Redirect Reference

When a hosted payment completes successfully, CtechPay redirects the customer to your redirectUrl with a reference query parameter.

https://example.com/payments/success?reference=TRANSACTION_OR_ORDER_REFERENCE

Use the reference to check the final payment status.

For card payments, the reference is the card order reference:

status = ctechpay.cards.status(reference)

For Airtel Money hosted payments, the reference is the Airtel transaction ID:

details = ctechpay.airtel.details(reference)

Airtel Money

Initiate Payment

payment = ctechpay.airtel.pay({
    "amount": 100,
    "phone": "0999123456",
    "category_flag": "LOAN_APPLICATION",
    "customer_reference": "INV-1001",
    "customer_message": "Invoice payment",
})

transaction_id = payment["data"]["transaction"]["id"]

Check Airtel Status

Use the transaction ID returned when initiating payment.

status = ctechpay.airtel.status(transaction_id)

Get Airtel Transaction Details

details = ctechpay.airtel.details(transaction_id)

Find CtechPay Transaction By Airtel Money ID

reference = ctechpay.airtel.reference("AIRTEL_MONEY_ID")

Card Hosted Bank Page

This creates the Standard Bank hosted card checkout page.

order = ctechpay.cards.create_payment_page({
    "amount": 100,
    "category_flag": "LOAN_APPLICATION",
    "merchantAttributes": True,
    "redirectUrl": "https://example.com/payments/success",
    "cancelUrl": "https://example.com/payments/cancelled",
    "customer_reference": "INV-1001",
    "customer_message": "Invoice payment",
})

print(order["payment_page_URL"])

Check Card Order Status

status = ctechpay.cards.status(order["order_reference"])

Flask Example

from flask import Flask, redirect, request, jsonify
from ctechpay import CtechPay

app = Flask(__name__)
ctechpay = CtechPay.client("YOUR_SERVICE_TOKEN")

@app.post("/pay")
def pay():
    payment = ctechpay.hosted_payments.create({
        "amount": 100,
        "category_flag": "LOAN_APPLICATION",
        "customer_reference": "ORDER-1001",
        "redirectUrl": "https://example.com/payments/success",
        "cancelUrl": "https://example.com/payments/cancelled",
    })

    return redirect(payment["data"]["hosted_payment_url"])

@app.get("/payments/success")
def payment_success():
    reference = request.args.get("reference")
    status = ctechpay.cards.status(reference)
    return jsonify(status)

Payment Categories

If the merchant has configured payment categories in CtechPay, pass the category flag when creating the payment. This lets CtechPay allocate the transaction to the right category for balances, reports, and category-based settlements.

payment = ctechpay.hosted_payments.create({
    "amount": 10500,
    "category_flag": "LOAN_APPLICATION",
    "customer_reference": "APP-1001",
    "customer_message": "Loan application fee",
    "redirectUrl": "https://example.com/payments/success",
    "cancelUrl": "https://example.com/payments/cancelled",
})

The Python SDK also accepts "categoryFlag" and sends it to CtechPay as "category_flag".

Supported payment category flows:

Method	Category field
ctechpay.hosted_payments.create({...})	"category_flag" or "categoryFlag"
ctechpay.airtel.pay({...})	"category_flag" or "categoryFlag"
ctechpay.cards.create_payment_page({...})	"category_flag" or "categoryFlag"

The flag must match an active payment category on the merchant account. Omit it when the payment should remain uncategorized.

Error Handling

The SDK throws CtechPayError for failed requests.

from ctechpay import CtechPayError

try:
    payment = ctechpay.hosted_payments.create({
        "amount": 100,
    })
except CtechPayError as error:
    print(error)
    print(error.status_code)
    print(error.response)

Security Notes

This SDK intentionally does not expose direct card PAN/CVV helpers. Use the CtechPay Hosted Payment Page for card collection unless your integration is formally approved for card-data handling.

Do not disable SSL verification in production.