Wallet API v1.
All amounts are integers in minor units (100 = 1.00). Call the API from your server with Authorization: Bearer YOUR_API_KEY. Wallets are closed-loop: a balance can only be spent at the merchant that issued it, and there is no withdrawal endpoint.
Create or fetch a wallet
Call this when a customer first uses your shop. It is safe to call again. Pass an optional
email and Kassara emails the customer their checkout codes and a receipt for every
top-up, payment and refund.
POST /v1/wallets
{ "customer_id": "cust_42", "display_name": "Ravi Kumar", "email": "ravi@example.com" }
→ 200 { "customer_id": "cust_42", "balance": 0, "currency": "inr", "status": "active" }
GET /v1/wallets/{customer_id}
Top up
Creates a pending top-up and returns a checkout URL. Redirect the customer there. Afterwards they are sent to return_url?topup=top_…&status=succeeded. The wallet is credited only after the gateway confirms payment, within your wallet policy limits.
On the Starter plan the customer pays the top-up plus a Kassara fee (3%, min. €0.50); the wallet is credited with amount only. Show the breakdown before checkout with the quote endpoint. Payment-provider processing fees are separate.
GET /v1/pricing/quote?amount=5000&customer_id=cust_42
→ 200 { "amount": 5000, "fee": 150, "total": 5150, "plan": "starter",
"fee_label": "3% Kassara fee (min. 0.50 EUR)" }
POST /v1/wallets/{customer_id}/topups
{ "amount": 5000, "return_url": "https://yourshop.com/wallet" }
→ 201 { "id": "top_…", "status": "pending", "amount": 5000, "fee": 150, "total": 5150,
"checkout_url": "https://…" }
GET /v1/topups/{topup_id}
→ 200 { "id": "top_…", "status": "succeeded", "amount": 5000, "fee": 150, "total": 5150 }
Wallet checkoutRecommended for orders
Create a checkout session from your server and redirect the customer to its url. On our hosted page they confirm the payment with a one-time code; only then is the wallet charged. Sessions expire after 15 minutes, can be paid once, lock after 5 wrong codes, and only redirect to your registered website. Always check the result server-side; never trust the status in the return URL.
POST /v1/checkout_sessions
Idempotency-Key: order-1007
{ "customer_id": "cust_42", "amount": 24900, "reference": "order-1007",
"description": "Weekly veg box",
"success_url": "https://yourshop.com/order/1007", "cancel_url": "https://yourshop.com/cart" }
→ 201 { "id": "cs_…", "status": "open", "url": "https://…/checkout/cs_…", "expires_at": "…" }
# customer returns to success_url?checkout=cs_…&status=paid, then verify:
GET /v1/checkout_sessions/{id}
→ 200 { "id": "cs_…", "status": "paid", "amount": 24900, "transaction_id": "txn_…" }
Direct chargeFor pre-authorised, merchant-initiated payments
Send an Idempotency-Key header so a retried request never charges twice. Returns 402 insufficient_funds if the balance is too low.
POST /v1/wallets/{customer_id}/charges
Idempotency-Key: order-1007
{ "amount": 24900, "reference": "order-1007", "description": "Weekly veg box" }
→ 201 { "id": "txn_…", "type": "charge", "amount": -24900, "balance": 75100 }
Refund
Refunds go back into the wallet, never to cash. Leave out amount for a full refund. A refund can never exceed the original charge.
POST /v1/refunds
{ "charge_id": "txn_…", "amount": 5000, "reason": "Missing tomatoes" }
Transactions
GET /v1/wallets/{customer_id}/transactions?limit=50
WebhooksKassara tells your server when money moves
Set your endpoint under API keys & webhooks in the dashboard. Kassara then POSTs a JSON event for wallet.topup.succeeded, checkout_session.completed, wallet.charge.succeeded and wallet.refund.succeeded. Answer with any 2xx status. Failed deliveries are retried with back-off and can be resent from the dashboard, so handle each event id only once.
POST https://yourshop.com/webhooks/kassara
Kassara-Event: checkout_session.completed
Kassara-Signature: t=1762591200,v1=5f2c…
{ "id": "evt_…", "type": "checkout_session.completed", "created": 1762591200,
"data": { "id": "cs_…", "status": "paid", "amount": 24900, "currency": "eur",
"reference": "order-1007", "customer_id": "cust_42", "transaction_id": "txn_…" } }
Always verify the signature with your signing secret before trusting an event: it is an HMAC-SHA256 of <t>.<raw body>. Reject events older than five minutes.
import hashlib, hmac, time
def verify(header, raw_body, secret):
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Errors
{ "error": { "code": "insufficient_funds", "message": "Wallet balance is too low", "balance": 1200 } }
Codes include invalid_api_key, merchant_not_approved, wallet_not_found, insufficient_funds, below_min_topup, above_max_topup, max_balance_exceeded, refund_exceeds_charge, topup_volume_limit and idempotency_conflict.