zarpay 1.1.0

Official Python SDK for the ZarPay payment gateway

ZarPay Python SDK

Official Python SDK for the ZarPay payment gateway.

Installation

pip install zarpay

Quick Start

from zarpay import ZarPay

client = ZarPay("sk_sandbox_xxxxxxxxxxxxx")

payment = client.payments.create(
    merchant_order_id="ORD-123",
    amount=1500,
    channel_id=1,
    customer_phone="03001234567",
)

print(payment["data"]["status"])
print(payment["data"]["payment_method_label"])

Payments

# Create a payment
payment = client.payments.create(
    merchant_order_id="ORD-456",
    amount=2500,
    channel_id=1,
    customer_phone="03001234567",
    metadata={"customer_name": "Ahmed Khan"},
    idempotency_key="unique-key-456",
)

# Get by ZarPay ID
payment = client.payments.get("ZP_abc123def456")

# Get by your order ID
payment = client.payments.get_by_order_id("ORD-456")

Refunds

refund = client.refunds.create(
    zarpay_id="ZP_abc123def456",
    amount=500,
    reason="Customer requested refund",
)

print(refund["data"]["status"])  # 'pending' — requires admin approval

Balance

balance = client.balance.get()

print("Available:", balance["data"]["available"])
print("Settled:", balance["data"]["settled"])
print("Unsettled:", balance["data"]["unsettled"])
print("Pending:", balance["data"]["pending"])

Settlements

settlements = client.settlements.list(status="PAID", page=1, limit=10)

for s in settlements["data"]["settlements"]:
    print(f"#{s['id']}: PKR {s['net_amount']} ({s['status']})")

Channels

channels = client.channels.list()

for ch in channels["data"]["channels"]:
    print(f"{ch['id']}: {ch['label']} ({ch['wallet_type']})")
    print(ch["logo_url"])

Verify Webhooks

from zarpay import verify_webhook

def webhook_handler(request):
    try:
        event = verify_webhook(
            raw_body=request.body,
            signature_header=request.headers["X-ZarPay-Signature"],
            secret="whsec_your_webhook_secret",
        )

        if event["event"] == "payment.completed":
            pass  # Fulfill the order
        elif event["event"] == "refund.completed":
            pass  # Update order status
        elif event["event"] == "settlement.paid":
            pass  # Record settlement

        return HttpResponse(status=200)
    except ValueError:
        return HttpResponse(status=400)

Error Handling

from zarpay import ZarPay, ZarPayAPIError

try:
    payment = client.payments.create(...)
except ZarPayAPIError as e:
    print(e.status_code)  # 400, 401, 409, etc.
    print(e.error)        # Human-readable error message

Configuration

client = ZarPay(
    "sk_sandbox_xxx",
    base_url="http://localhost:3550/api/v1",
    timeout=60,
)

API Reference

Resource	Method	Endpoint
payments.create()	POST	/payments
payments.get()	GET	/payments/:id
payments.get_by_order_id()	GET	/payments/by-order/:id
refunds.create()	POST	/refunds
balance.get()	GET	/balance
settlements.list()	GET	/settlements
channels.list()	GET	/channels
verify_webhook()	—	Verify webhook signature

License

MIT