Fawaterak SDK

Overview

An open-source Python SDK for Fawaterak, one of Egypt’s major payment gateways. There was no official Python client for the API, so integrations meant hand-rolling requests calls, manual OAuth token refresh, and no type safety anywhere in the payment flow. This SDK wraps the v3 API into a typed, thread-safe client.

OAuth2 & Token Management

The core of the SDK is its token layer. It implements the client_credentials and refresh_token flows with automatic caching and expiry-aware renewal, so callers never have to think about token lifecycle. A thread-safe refresh lock ensures concurrent requests never fire duplicate /oauth/token calls — a common bug in naive integrations under load.

Key Features

• Token Management — cached, expiry-aware OAuth2 with thread-safe refresh
• Two Transaction Modes — hosted checkout (result.url) and direct payment (result.payment_data), unified under a discriminated PaymentResult type
• Typed Models — dataclasses for customers, cart items, and transactions that serialize to exact API payload shapes
• Error Handling — a dedicated exception hierarchy for network, auth, validation, and transient API errors
• Core Client — get_payment_methods, create_transaction, get_transaction, and list_transactions covering the full transaction lifecycle