Esaalat server SDK for Python

Python 3.8+

Create the checkout session, attach the buyer's reference and verify signed webhooks from a Django, Flask or FastAPI server. Standard library only — nothing to audit, nothing to pin.

Install

pip install esaalat

Create the session

esaalat

from esaalat import EsaalatClient

# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
esaalat = EsaalatClient.from_env()

session = esaalat.create_session(order_id="order-12345", amount=5000)

session["session_token"]  # → open the checkout from your page
session["portal_url"]     # → or redirect the buyer straight to it

Verify the webhook

Flask webhook route

from esaalat import EsaalatWebhookError

@app.post("/esaalat/webhooks")
def esaalat_webhook():
    try:
        event = esaalat.verify_webhook(
            request.data,                            # the RAW body
            request.headers["X-Esaalat-Signature"],
        )
    except EsaalatWebhookError:
        return "", 400                               # anything but 2xx retries

    if event["event"] == "payment.verified":
        release_order(event["order_id"])              # idempotent on intent_id
    return "", 200

Verify the signature over the raw body. Re-serializing it changes the bytes and the signature will not match — which is the correct outcome, because a re-serialized body proves nothing.

What it handles for you

•Token cached — One token per process, refreshed from the JWT's own exp a minute early, so an integration does not start returning 401s at the hour boundary.
•Idempotency automatic — One key per create call, reused on every retry: a 429 or a timeout cannot create the same order twice.
•Retries — 429, 5xx and network failures, honouring Retry-After.
•Typed errors — Every failure carries a code, the HTTP status, the offending field and the API's per-field errors.
•Server-only — Only the session token reaches the browser. The client secret stays on your server, where it belongs.

Configuration

Argument	Environment variable	Default
`client_id`	`ESAALAT_CLIENT_ID`	required
`client_secret`	`ESAALAT_CLIENT_SECRET`	required
`webhook_secret`	`ESAALAT_WEBHOOK_SECRET`	needed by `verify_webhook`
`base_url`	`ESAALAT_BASE_URL`	`https://api.esaalat.com/api/v1`
`timeout`	`—`	`20` seconds
`max_retries`	`—`	`2`

Before you go live

•The package has no dependencies: it uses urllib, hmac and json from the standard library.
•The client secret is a server secret. Never call it from a browser or ship it in a mobile app.
•Amounts are whole Yemeni riyals; format_amount(5000.5) refuses before the request is sent.

Merchant API reference

Create the session

esaalat

from esaalat import EsaalatClient

# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
esaalat = EsaalatClient.from_env()

session = esaalat.create_session(order_id="order-12345", amount=5000)

session["session_token"]  # → open the checkout from your page
session["portal_url"]     # → or redirect the buyer straight to it

Verify the webhook

Flask webhook route

from esaalat import EsaalatWebhookError

@app.post("/esaalat/webhooks")
def esaalat_webhook():
    try:
        event = esaalat.verify_webhook(
            request.data,                            # the RAW body
            request.headers["X-Esaalat-Signature"],
        )
    except EsaalatWebhookError:
        return "", 400                               # anything but 2xx retries

    if event["event"] == "payment.verified":
        release_order(event["order_id"])              # idempotent on intent_id
    return "", 200

Verify the signature over the raw body. Re-serializing it changes the bytes and the signature will not match — which is the correct outcome, because a re-serialized body proves nothing.

What it handles for you

•Token cached — One token per process, refreshed from the JWT's own exp a minute early, so an integration does not start returning 401s at the hour boundary.

•Idempotency automatic — One key per create call, reused on every retry: a 429 or a timeout cannot create the same order twice.

•Retries — 429, 5xx and network failures, honouring Retry-After.

•Typed errors — Every failure carries a code, the HTTP status, the offending field and the API's per-field errors.

•Server-only — Only the session token reaches the browser. The client secret stays on your server, where it belongs.

Argument

Environment variable

Default

client_id

ESAALAT_CLIENT_ID

required

client_secret

ESAALAT_CLIENT_SECRET

required

webhook_secret

ESAALAT_WEBHOOK_SECRET

needed by verify_webhook

base_url

ESAALAT_BASE_URL

https://api.esaalat.com/api/v1

timeout

—

20 seconds

max_retries

—

2