Metadata-Version: 2.4
Name: ctechpay
Version: 0.1.0
Summary: Official Python SDK for CtechPay hosted payments, Airtel Money, and card status checks.
Author: CtechPay
License: MIT
Project-URL: Homepage, https://ctechpay.com
Project-URL: Documentation, https://new-api.ctechpay.com/docs/integration
Project-URL: Repository, https://github.com/ctechpay/ctechpay-python
Keywords: ctechpay,payments,hosted-payments,airtel-money,malawi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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

```bash
pip install ctechpay
```

## Basic Usage

```python
from ctechpay import CtechPay

ctechpay = CtechPay.client("YOUR_SERVICE_TOKEN")
```

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

```python
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.

```python
payment = ctechpay.hosted_payments.create({
    "amount": 100,
    "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.

```text
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:

```python
status = ctechpay.cards.status(reference)
```

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

```python
details = ctechpay.airtel.details(reference)
```

## Airtel Money

### Initiate Payment

```python
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.

```python
status = ctechpay.airtel.status(transaction_id)
```

### Get Airtel Transaction Details

```python
details = ctechpay.airtel.details(transaction_id)
```

### Find CtechPay Transaction By Airtel Money ID

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

## Card Hosted Bank Page

This creates the Standard Bank hosted card checkout page.

```python
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

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

## Flask Example

```python
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.

```python
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.
