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

• Explicit configuration via constructor arguments or environment variables.
• OAuth2 token management (client_credentials + refresh_token flows) with automatic caching and expiry-aware renewal.
• Thread-safe token refresh so concurrent callers do not issue duplicate /oauth/token requests.
• Central HTTP client with bearer-token injection, transport-level retries, and Fawaterak-specific error mapping.
• Exception hierarchy for network, authentication, validation, and transient API errors.
• FawaterakClient with get_payment_methods, create_transaction, get_transaction, and list_transactions covering the core transaction flow.
• E-invoicing with create_einvoice, get_einvoice, list_einvoices, update_einvoice, and delete_einvoice for shareable, multi-attempt payment links.
• Webhook verification and parsing with HMAC signature checks and typed event dataclasses (PaidWebhookEvent, FailedWebhookEvent, CancelWebhookEvent, RefundWebhookEvent).
• Two transaction modes — hosted checkout (result.url) and direct payment (result.payment_data), with a discriminated PaymentResult union for card redirects, reference codes (Fawry/Aman/Masary), and mobile wallets.
• Typed dataclass models (Customer, CartItem, TransactionData, Page, etc.) that serialize to the exact API payload shapes.

Support me with a star here,