Developers

API Reference

REST over HTTPS. JSON in, JSON out. Authenticate with HTTP Basic using your secret key.

Base URL

https://api.beys.co.tz/v1

Authentication

Send your secret key as the basic-auth username, with no password. Get keys from the dashboard.

curl https://api.beys.co.tz/v1/charges \
  -u sk_live_4eC39HqLyjWDarjtT1zdp7dc: \
  -d amount=2000 \
  -d currency=tzs

Supported currencies

Beys accepts charges in tzs (Tanzanian Shilling) and usd (US Dollar). Amounts are always expressed in the smallest unit — cents for USD, and TZS is sent as a whole-number amount × 100 for consistency with the cents convention.

Payment methods

Pass payment_method on /v1/charges to route a transaction explicitly. If omitted, Beys infers it from the source token.

payment_method	Label	Region	Example source token
card	Cards — Visa, Mastercard, Amex, Discover, JCB, UnionPay, Diners	Global	tok_visa
paypal	PayPal	Global	tok_paypal
stripe	Stripe-routed	Global	tok_stripe
apple_pay	Apple Pay	Global	tok_applepay
google_pay	Google Pay	Global	tok_googlepay
mpesa	M-Pesa	Tanzania	tok_mpesa
tigopesa	Mixx by Yas	Tanzania	tok_tigopesa
airtel	Airtel Money	Tanzania	tok_airtel
halopesa	HaloPesa	Tanzania	tok_halopesa
bank	Bank transfer	Tanzania	tok_bank

curl https://api.beys.co.tz/v1/charges \
  -u sk_live_4eC39HqLyjWDarjtT1zdp7dc: \
  -d amount=50000 \
  -d currency=tzs \
  -d payment_method=mpesa \
  -d source=tok_mpesa

Mobile-money charges return status: "pending" until the customer confirms the USSD push. You'll receive a charge.succeeded webhook on confirmation.

Endpoints

POST

/v1/charges

Create a new charge. Supports Idempotency-Key header.

GET

/v1/charges

List charges. Cursor-paginated.

GET

/v1/charges/:id

Retrieve a single charge by id.

POST

/v1/charges/:id/refund

Refund a charge, full or partial.

POST

/v1/customers

Create a saved customer with tokenized payment methods.

POST

/v1/webhooks

GET

/v1/balance

Retrieve current available and pending balance.

GET

/v1/payouts

List payouts to your linked bank account.

Idempotency

Any POST accepts an Idempotency-Key header. Retries with the same key within 24h return the original response — never a duplicate charge.

Webhook signatures

Every webhook carries a Beys-Signature header: HMAC-SHA256 of the raw body, signed with your endpoint's secret. Verify before processing.

const expected = crypto
  .createHmac("sha256", endpointSecret)
  .update(rawBody)
  .digest("hex");
if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return res.status(401).end();
}

Errors

Standard HTTP codes. Error bodies always include type, code, and a human message. Rate-limited responses return 429 with a Retry-After header.

SDKs

Official: TypeScript, Go, Python, Ruby, PHP, Java. Install via your package manager — e.g. npm i @beys/node.