Developer quick start · staging

Build recurring ETB access around one mandate.

Create a subscription once, listen for renewal outcomes, and protect access with LEWAM’s graceful dunning ladder.

Staging API basehttps://etb-billing-sandbox.onrender.com

AuthorizationBearer sk_test_yeshay_01

Interactive simulationkiraweb.pro.et/lewam-demo/ ↗

01 · Enrollment

Create a subscription

When a creator chooses a monthly plan, call the staging API from your server. Amounts are integer cents: 500 ETB is 50000.

POST /v1/subscriptions

curl -X POST https://etb-billing-sandbox.onrender.com/v1/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_yeshay_01' \
  -d '{
    "phone": "0911223344",
    "name": "Creator Name",
    "plan_name": "YeShay Pro Monthly",
    "amount": 50000
  }'

200 · subscription.active

{
  "id": "sub_a960ea682d30eb25bb",
  "status": "active",
  "mandate_id": "MND_781d58343511",
  "current_period_end": "2026-10-26T19:00:00.000Z",
  "mandate_deep_link": "merchant://10000000016?mctShortCode=199183&..."
}

Next: launch mandate_deep_link so the customer authorizes the Telebirr mandate with their PIN once.

02 · Silent renewal

Listen for invoice.paid

On Day 30, LEWAM attempts the mandate debit silently and notifies your server when the billing period rolls forward.

POST /api/webhooks/lewam

{
  "event": "invoice.paid",
  "data": {
    "subscription_id": "sub_a960ea682d30eb25bb",
    "customer_phone": "0911223344",
    "amount": 50000,
    "currency": "ETB",
    "period_end": "2026-11-26T19:00:00.000Z"
  }
}

Your action: extend the creator’s Pro access for another billing period after verifying the webhook.

03 · Recovery

Handle low-balance protection

If the wallet is empty, LEWAM preserves access while retrying at +1 day → +3 days → +7 days before cancellation.

invoice.payment_failed · 40401

{
  "event": "invoice.payment_failed",
  "data": {
    "subscription_id": "sub_a960ea682d30eb25bb",
    "status": "past_due",
    "error_code": "40401",
    "next_retry_at": "2026-10-27T19:00:00.000Z"
  }
}

Recommended UX: show a quiet banner: “Your Pro renewal couldn’t process. Please top up your Telebirr wallet before tomorrow.”

Reference · Request shape

Subscription parameters

All required fields are validated before a mandate is created. Amounts are integer cents, not decimal ETB.

phonestring · required

Customer’s Telebirr phone number, for example 0911223344.

namestring · required

Customer’s full name.

plan_namestring · required

Your tier name, for example YeShay Pro Monthly.

amountinteger · required

Billing amount in cents: 50000 represents 500.00 ETB.

intervalstring · optional · default: month

Billing frequency: month or year.

04 · Production readiness

Production deployment & fund settlement

LEWAM is strictly non-custodial in production. Payments settle directly from the customer’s Telebirr wallet into your company’s Telebirr Merchant Account / Shortcode through Ethio Telecom’s SuperApp gateway.

What your team provides

To transition from staging, your company binds its Telebirr Shortcode and Fabric keys in LEWAM’s secure vault. LEWAM never holds customer funds; it orchestrates mandates, billing state, retries, and webhook delivery.

Recommended rollout: verify the full sandbox lifecycle first, share your merchant onboarding details, then receive production credentials and complete a controlled live-money test.

05 · Reliability

Handle errors predictably

Return a useful message to your user, log the request ID on your server, and never expose secret keys in browser code.

40401Insufficient wallet balanceSubscription becomes past_due; automatic retries are scheduled at +1d, +3d, and +7d.

40101Invalid API keyCheck the Bearer token and environment. Do not retry unchanged credentials.

401Missing API keyAdd Authorization: Bearer <key> to server-side requests.

400Invalid requestA required parameter is missing or has the wrong type. Validate before sending.

Example error response

{
  "error": {
    "code": "40401",
    "message": "Insufficient wallet balance"
  }
}

06 · Integration notes

Keep the boundary safe

Server-side only

Keep the staging secret in your server environment. Never ship it in browser JavaScript.

Verify webhooks

Validate the sender signature and make event handling idempotent before changing access.

Sandbox status

This staging engine is simulated and does not move real money.

Need help?

Coordinate with Kirubel Daniel and the LEWAM engineering team for staging integration support.