Use Amnen Pay on any website

What you are integrating

Customers on your site already have (or will create) an Amnen Pay wallet. When they pay or deposit, they are sent to Amnen’s branded hosted checkout, confirm with SMS OTP, and Amnen moves money from their wallet. When they withdraw, your server tells Amnen to credit that wallet by phone number. You never handle the wallet PIN yourself.

This is not a betting-only product. Industry is a label when the Amnen operator connects your business. The keys, APIs, and checkout page are the same for every kind of website.

1. Get keys from Amnen Admin

1. An Amnen operator opens /admin/checkout and connects your business (name + industry + optional Amnen countries). Webhook URL is not required yet.
2. Copy the share pack: publishable (amnen_pk_live_), secret (amnen_live_), and webhook secret (amnen_whsec_). Secret and webhook are shown once.
3. Put them in server env: AMNEN_PUBLISHABLE_KEY, AMNEN_SECRET_KEY, AMNEN_WEBHOOK_SECRET.
4. Validate with GET /api/v1/checkout/account. Then generate your webhook URL and POST it to /api/v1/checkout/webhook-endpoint.
5. Only offer Amnen Pay to users whose country and currency are in the account response and already supported by your product.

curl https://www.amnenpay.com/api/v1/checkout/account \
  -H "X-API-Key: amnen_live_YOUR_SECRET"

2. Deposit from Amnen wallet

Call this from your backend when the customer clicks Pay or Deposit. Then redirect their browser to paymentUrl. Credit your own balance only after Status says completed, using netAmount.

curl -X POST https://www.amnenpay.com/api/v1/checkout/deposit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: amnen_live_YOUR_SECRET" \
  -d '{
    "userId": "customer-42",
    "amount": 500,
    "currency": "ETB",
    "reference": "site_dep_9f2c1a",
    "callbackUrl": "https://yoursite.com/api/webhooks/amnenpay",
    "redirectUrl": "https://yoursite.com/wallet/return?ref=site_dep_9f2c1a"
  }'

3. Withdraw to Amnen wallet

Debit the customer on your ledger first, then call withdraw with their phone. Amnen credits the matching Amnen wallet. If the call fails, refund your ledger. Samereference is idempotent.

curl -X POST https://www.amnenpay.com/api/v1/checkout/withdraw \
  -H "Content-Type: application/json" \
  -H "X-API-Key: amnen_live_YOUR_SECRET" \
  -d '{
    "userId": "customer-42",
    "amount": 200,
    "currency": "ETB",
    "reference": "site_wd_7aa1",
    "phone": "+251912345678",
    "name": "Customer Name"
  }'

4. Verify webhooks

HMAC-SHA256 of `${timestamp}.${rawBody}` with the webhook secret. Header X-Amnen-Signature isv1=<hex>. Reject timestamps older than 5 minutes. Then re-check Status before moving money.

const provided = (req.headers['x-amnen-signature'] || '').replace(/^v1=/i, '');
const ts = req.headers['x-amnen-webhook-timestamp'];
const expected = crypto
  .createHmac('sha256', process.env.AMNEN_WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`)
  .digest('hex');

Endpoints

`/api/v1/betting/*` remains as an alias of `/api/v1/checkout/*`.

Full written guide

The complete process, error codes, Node examples, and how to share keys with other business owners live in docs/WALLET-CHECKOUT.md in the Amnen Pay repository.