ctechpay 0.1.0

Official Python SDK for CtechPay hosted payments, Airtel Money, and card status checks.

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,
    "customer_reference": "INV-1001",
    "customer_message": "Invoice payment",
    "customer_name": "Jane Doe",
    "customer_email": "[e-mail]",
    "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",
    "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,
    "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,
        "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)

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.