ZeePay API Documentation

Quickstart

Install the SDK and create your first payment:

npm install zeepay

import ZeePay from "zeepay";
const zee = new ZeePay(process.env.ZEEPAY_SECRET_KEY);

const payment = await zee.payments.create({
  amount: 10,
  currency: "USD",
  reference: "invoice_1042"
});
// Redirect the customer to payment.checkoutUrl

Authentication

Authenticate with a secret key in the Authorization: Bearer zp_sk_... header. Use zp_test_sk_... keys in sandbox mode — no real payments are processed. Never expose secret keys in client-side code.

API Reference

Full OpenAPI 3.0 specification: docs/openapi.yaml

Subscriptions & Auto-Deduct

ZeePay subscriptions debit your customers automatically on each billing date — including EcoCash, InnBucks and Omari wallets that don't natively support recurring payments. A mandate is created when you create a subscription; the customer approves it once, then ZeePay handles every debit.

1. Create: POST /v1/subscriptions with methodCode,amount, interval and customer details.
2. Approve: the customer authorizes once (wallet PIN / card 3DS) via the returned approvalUrl. In sandbox, callPOST /v1/subscriptions/:id/approve to simulate it.
3. Auto-deduct: the billing engine debits on eachnextBillingDate. Failed debits retry automatically (subscription becomespast_due) until maxRetries is exhausted.

const sub = await zee.subscriptions.create({
  merchantReference: "plan_premium",
  amount: 9.99,
  currency: "USD",
  interval: "monthly",
  methodCode: "ecocash",           // auto-deduct EcoCash monthly!
  customerPhone: "+263771234567"
});
// Redirect customer to sub.approvalUrl to authorize the mandate

Payouts & Disbursements

Send money out to customer wallets via the EcoCash EPG services — synchronous, PIN-free, and idempotent on your externalReference.

const payout = await zee.payouts.create({
  serviceType: "enterprise_cash_in",
  amount: 150.00,
  currency: "USD",
  recipientMsisdn: "263777000000",
  externalReference: "payroll-2024-01-emp042", // idempotency key
  beneficiaryReference: "Emp042"
});
// Result is synchronous — payout.status is "succeeded" immediately

Webhooks

ZeePay sends signed events to your endpoint. Verify signatures using HMAC-SHA256 with your webhook secret in the X-ZeePay-Signature header. Failed deliveries retry up to 5 times with exponential backoff.

Errors & Idempotency

Errors use conventional HTTP codes — 4xx for client errors and 5xx for platform errors. All create endpoints accept an Idempotency-Key header to safely retry requests without duplicating charges.