Official Python SDK for Snippe Payment API - Accept payments via mobile money, card, and QR code in East Africa.
pip install snippefromsnippeimportSnippe, Customerclient=Snippe("your_api_key")
# Create a mobile money paymentpayment=client.create_mobile_payment(
amount=1000,
currency="TZS",
phone_number="0788500000",
customer=Customer(firstname="John", lastname="Doe"),
)
print(f"Payment reference: {payment.reference}")
print(f"Status: {payment.status}")Customer receives a USSD prompt on their phone to confirm payment.
payment=client.create_mobile_payment(
amount=5000,
currency="TZS",
phone_number="0712345678",
customer=Customer(
firstname="Jane",
lastname="Doe",
email="jane@example.com"# optional
),
webhook_url="https://yourapp.com/webhooks", # optionalmetadata={"order_id": "ORD-123"}, # optional
)Returns a payment_url to redirect the customer to complete payment.
payment=client.create_card_payment(
amount=50000,
currency="TZS",
phone_number="0712345678",
customer=Customer(
firstname="John",
lastname="Doe",
email="john@example.com",
address="123 Main Street",
city="Dar es Salaam",
state="DSM",
postcode="14101",
country="TZ",
),
callback_url="https://yourapp.com/callback", # required for cardwebhook_url="https://yourapp.com/webhooks",
)
# Redirect customer to this URLprint(payment.payment_url)Returns a QR code for the customer to scan.
payment=client.create_qr_payment(
amount=25000,
currency="TZS",
phone_number="0712345678",
customer=Customer(firstname="John", lastname="Doe"),
)
# Display this QR code to customerprint(payment.payment_qr_code)
print(payment.payment_token)payment=client.get_payment("payment_reference")
print(f"Status: {payment.status}") # pending, completed, failed, expired, voidedresult=client.list_payments(limit=20, offset=0)
forpaymentinresult.payments:
print(f"{payment.reference}: {payment.status}")balance=client.get_balance()
print(f"Available: {balance.available_balance}{balance.currency}")Send money to mobile money accounts and bank accounts.
Send money to Airtel Money, Mixx by Yas (Tigo), and HaloPesa.
Calculate fee first (recommended)
fee=client.calculate_payout_fee(amount=5000)
print(f"Fee: {fee.fee_amount}{fee.currency}")
print(f"Total to deduct: {fee.total_amount}{fee.currency}")Create mobile money payout
payout=client.create_mobile_payout(
amount=5000,
recipient_name="John Doe",
recipient_phone="255781000000", # Format: 255XXXXXXXXXnarration="Salary payment January 2026",
webhook_url="https://yourapp.com/webhooks",
metadata={"employee_id": "EMP-001"},
idempotency_key="unique_id_123"# Prevent duplicates
)
print(f"Payout reference: {payout.reference}")
print(f"Status: {payout.status}")
print(f"Amount: {payout.amount.value}{payout.amount.currency}")
print(f"Fee: {payout.fees.value}{payout.fees.currency}")Send money to 40+ Tanzanian banks including CRDB, NMB, NBC, and ABSA.
payout=client.create_bank_payout(
amount=50000,
recipient_name="John Doe",
recipient_bank="CRDB", # Bank code from supported banks listrecipient_account="0211049375",
narration="Invoice payment INV-2026-001",
webhook_url="https://yourapp.com/webhooks",
metadata={"invoice_id": "INV-2026-001"},
)
print(f"Reference: {payout.reference}")
print(f"Status: {payout.status}")List Payouts
result=client.list_payouts(limit=10, offset=0)
print(f"Total payouts: {result.total}")
forpayoutinresult.items:
print(f"{payout.reference}: {payout.status} - {payout.amount.value}{payout.amount.currency}")
GetPayoutStatuspythonpayout=client.get_payout("payout_reference")
print(f"Status: {payout.status}")
ifpayout.status=="failed":
print(f"Reason: {payout.failure_reason}")Get Payout Status
payout=client.get_payout("payout_reference")
print(f"Status: {payout.status}")
ifpayout.status=="failed":
print(f"Reason: {payout.failure_reason}")| Status | Description |
|---|---|
pending | Payout created, awaiting processing |
completed | Payout successful, recipient received funds |
failed | Payout failed (check failure_reason) |
reversed | Payout was reversed after completion |
Verify and parse webhook events from Snippe.
fromsnippeimportverify_webhook, WebhookVerificationError# In your webhook endpointtry:
payload=verify_webhook(
body=request.body.decode(),
signature=request.headers["X-Webhook-Signature"],
timestamp=request.headers["X-Webhook-Timestamp"],
signing_key="your_webhook_signing_key",
)
ifpayload.event=="payment.completed":
print(f"Payment {payload.reference} completed!")
# Fulfill the orderelifpayload.event=="payment.failed":
print(f"Payment {payload.reference} failed")
# Notify customerelifpayload.event=="payout.completed":
print(f"Payout {payload.reference} completed!")
elifpayload.event=="payout.failed":
print(f"Payout {payload.reference} failed")
exceptWebhookVerificationErrorase:
print(f"Invalid webhook: {e}")| Event | Description |
|---|---|
payment.completed | Payment successful |
payment.failed | Payment declined or failed |
payment.expired | Payment timed out |
payment.voided | Payment cancelled |
For async applications (FastAPI, aiohttp, etc.):
fromsnippeimportAsyncSnippe, Customerasyncdefcreate_payment():
asyncwithAsyncSnippe("your_api_key") asclient:
payment=awaitclient.create_mobile_payment(
amount=1000,
currency="TZS",
phone_number="0788500000",
customer=Customer(firstname="John", lastname="Doe"),
)
returnpaymentPrevent duplicate payments by providing an idempotency key:
payment=client.create_mobile_payment(
amount=1000,
currency="TZS",
phone_number="0788500000",
customer=Customer(firstname="John", lastname="Doe"),
idempotency_key="unique_order_id_123", # Your unique identifier
)fromsnippeimport (
Snippe,
AuthenticationError,
ValidationError,
NotFoundError,
ForbiddenError,
ConflictError,
UnprocessableEntityError,
RateLimitError,
ServerError,
)
try:
payment=client.create_mobile_payment(...)
exceptAuthenticationError:
print("Invalid API key")
exceptValidationErrorase:
print(f"Invalid request: {e.message}")
exceptNotFoundError:
print("Payment not found")
exceptForbiddenError:
print("Not authorized for this operation")
exceptConflictError:
print("Resource already exists")
exceptUnprocessableEntityError:
print("Idempotency key mismatch")
exceptRateLimitError:
print("Too many requests, slow down")
exceptServerError:
print("Snippe server error, try again later")| Currency | Country |
|---|---|
| TZS | Tanzania |
| KES | Kenya |
| UGX | Uganda |
MIT