Skip to content

API reference

This page is generated from the SDK source docstrings.

Client

FawaterakClient

High-level client for Fawaterak API v3 transaction endpoints.

get_payment_methods() cached

Return all integration-enabled payment methods for this vendor.

create_transaction(*, currency, customer, cart_items, cart_total, payment_method_id=None, mobile_wallet_number=None, save_customer=False, pay_load=None, redirection_urls=None, send_email=False, send_sms=False, due_date=None, tr_number=None, redirect_option=False, auth_and_capture=None, tax_data=None, discount_data=None, list_style='h', lang='en')

Create a transaction in hosted-checkout or direct-payment mode.

get_transaction(intent_key)

Fetch one transaction by its intent key.

list_transactions(*, start_date, end_date, page=1, per_page=15, pay_load=None)

Return a paginated export of persisted transactions.

create_einvoice(*, currency, customer, cart_items, cart_total, due_date=None, invoice_number=None, pay_load=None, redirection_urls=None)

Creates an e-invoice

get_einvoice(invoice_id)

Gets a specific e-invoice based on invoice_id

list_einvoices(einvoice_filter=None)

Lists e-invoice based on filter (if found).

Returns in paginated response in pages of 10.

update_einvoice(*, invoice_id, customer, currency=None, products=None, has_history=False, due_date=None, invoice_number=None, tags=None)

Updates an existing e-invoice. When has_history is not set, currency and products are required and line items are replaced.

delete_einvoice(invoice_id)

Deletes an unpaid e-invoice.

The API refuses deletion if active payment references block it. (That's what docs say, can't replicate it) Returns True on a successful deletion response.

Can't understand how they don't soft delete, they just go full delete, like not just a status saying deleted (Soft-deletion).

parse_paid_webhook(payload)

Verify and parse a paid/pending webhook payload.

parse_failed_webhook(payload)

Verify and parse a failed-payment webhook payload.

parse_cancel_webhook(payload)

Verify and parse a cancel/expired webhook payload.

parse_refund_webhook(payload)

Verify and parse a refund webhook payload.

parse_webhook(payload, webhook_type)

Verify and parse a webhook payload of the given type.

Configuration

Config dataclass

Resolved configuration used to construct TokenManager/HTTPClient.

Construct this via Config.resolve(...) rather than directly for first-time — that's where env var fallback and validation happen, subsequent usage can use Config() directly since it returns the singelton object.

Attributes:

Name Type Description
client_id str

OAuth client id, used for the /api/v3/* endpoints.
client_secret str

OAuth client secret. Excluded from repr()/logs.
base_url str

Resolved from environment, or a direct override (e.g. to point at a local mock server in tests).
environment Environment | None

"staging" or "production" if a recognized one was given; None if base_url was supplied directly instead.
vendor_api_key str | None

Legacy static key, only needed for the Phase 8 tokenization endpoints and for webhook signature verification. Optional because most of the SDK's v3 surface never uses it. Excluded from repr()/logs.
timeout float

Default per-request timeout, in seconds.

resolve(*, client_id=None, client_secret=None, environment=None, base_url=None, vendor_api_key=None, timeout=DEFAULT_TIMEOUT_SECONDS) classmethod

Build a Config from explicit args, falling back to env vars.

Precedence:
    - explicit argument
    - matching env var.

Args:
    - client_id: OAuth client id. Falls back to $FAWATERAK_CLIENT_ID.
    - client_secret: OAuth client secret. Falls back to
        $FAWATERAK_CLIENT_SECRET.
    - environment: "staging" or "production". Falls back to
        $FAWATERAK_ENV. Ignored if `base_url` is also given.
    - base_url: Explicit API base URL, overriding `environment`
        entirely. Mainly for pointing at a local mock server in tests.
    - vendor_api_key: Legacy vendor key, needed only for Phase 8
        (tokenization) and webhook verification. Falls back to
        $FAWATERAK_VENDOR_API_KEY.
    - timeout: Default per-request timeout, in seconds.

Raises:
FawaterakConfigError: if client_id/client_secret are missing after
    checking both the argument and env var, or if no valid
    `environment` was resolved and no `base_url` override was
    given either.

Models

Customer dataclass

Customer details attached to a transaction or e-invoice.

maps to https://app.fawaterk.com/documentation#models/Customer

CartItem dataclass

One line item in a transaction cart.

maps to https://app.fawaterk.com/documentation#models/CartItem

RedirectionUrls dataclass

Customer redirect URLs and optional per-transaction webhook override.

maps to https://app.fawaterk.com/documentation#models/RedirectionUrls

EInvoice dataclass

Full e-invoice detail returned by get/update and list items.

The documentation leaves this shape unknown ("Full e-invoice detail object"), so fields mirror what was observed on staging and parsing is defensive: missing or unexpected keys degrade to defaults instead of raising.

invoice_id maps from the payload's id key; the API identifies invoices by invoice_id in requests.

EinvoiceCreationResult dataclass

Result of successful E-Invoice creation.

maps to https://staging.fawaterk.com/documentation#models/CreateEinvoiceSuccess

EinvoiceFilter dataclass

Optional filter for listing e-invoices.

maps to https://staging.fawaterk.com/documentation#models/ListEinvoicesRequest

Exceptions

exceptions

Fawaterak SDK exception module.

FawaterakError
├── FawaterakConnectionError        # network/timeout, safe to retry
├── FawaterakWebhookError           # signature mismatch / malformed webhook body
└── FawaterakAPIError               # non-2xx with parsed {status, message} body
    ├── FawaterakAuthError          # 401 (after one failed refresh-and-retry)
    ├── FawaterakValidationError    # 400/422
    └── FawaterakTemporaryError     # 503 — safe to retry with backoff

FawaterakException

Bases: BaseException

Base class for every exception the SDK raises

FawaterakAPIException

Bases: FawaterakException

Fawaterak API returned a non-2xx response

FawaterakAuthException

Bases: FawaterakAPIException

Error 401: OAuth failed even after refresh and retry (Bad Credentials)

FawaterakConfigException

Bases: FawaterakException

The SDK was misconfigured — missing credentials, an unrecognized environment.

FawaterakConnectionException

Bases: FawaterakException

Network-level exception where no response was received

FawaterakTemporaryException

Bases: FawaterakAPIException

Error 503: transient safe to retry with backoff

FawaterakValidationException

Bases: FawaterakAPIException

Error 400/422: bad request, non-retryable as-is

FawaterakWebhookException

Bases: FawaterakException

Webhook failed signature verification or parsing