Quickstart

This walks through accepting a payment end to end. In test mode everything is deterministic, so you can run it right now without moving real money.

You will need a secret API key (sk_test_…). See Authentication if you don’t have one yet.

1. Register a webhook endpoint (once)

Register the URL that should receive events, and store the returned signing secret (whsec_…). It is shown once.

curl -X POST https://api.bizzle.my/v1/webhooks \
  -H "Authorization: Bearer sk_test_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/bizzle/webhook", "events": ["payment.succeeded", "payout.completed"]}'

2. Create a payment

Send an Idempotency-Key so a retried request can’t double-charge.

curl -X POST https://api.bizzle.my/v1/payments \
  -H "Authorization: Bearer sk_test_yourkey" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "currency": "TZS", "description": "Order #1042"}'

The response includes id (pay_…), status: "pending", a checkout_url, and the computed fee and net:

{
  "id": "pay_…",
  "status": "pending",
  "checkout_url": "https://…",
  "fee": 2450,
  "net": 47550
}

Redirect the customer to checkout_url. In test mode the sandbox provider completes deterministically.

3. Receive the webhook

When the provider confirms payment, Bizzle fires payment.succeeded to your endpoint. Always verify the signature before trusting the payload:

import crypto from "node:crypto";

app.post("/bizzle/webhook", (req, res) => {
  const signature = req.get("X-Webhook-Signature");
  const expected = crypto
    .createHmac("sha256", process.env.BIZZLE_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body)) // raw JSON, exactly as received
    .digest("hex");

  if (signature !== expected) return res.status(400).end();
  // handle the event…
  res.status(200).end();
});

See Webhooks for the full header list and verification model.

4. Verify and reconcile

• GET /v1/payments/:id — the payment’s status, fee, net, payout_status.
• GET /v1/balance — your current balance.
• GET /v1/logs — recent requests from your keys.

5. Payouts

Vendor payouts happen automatically as part of settlement. To pay a vendor directly:

curl -X POST https://api.bizzle.my/v1/payouts \
  -H "Authorization: Bearer sk_test_yourkey" \
  -H "Idempotency-Key: payout-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 47550, "currency": "TZS", "method": {"type": "mobile_money", "network": "mpesa", "msisdn": "2557…"}}'

Using the SDKs instead

// Node
import { BizzleClient } from "@bizzle/sdk-node";
const bizzle = new BizzleClient({ apiKey: process.env.BIZZLE_SECRET_KEY });
const payment = await bizzle.createPayment({
  body: { amount: 50000, currency: "TZS", description: "Order #1042" },
  idempotencyKey: "order-1042",
});

# Python
from bizzle import BizzleClient
client = BizzleClient(api_key="sk_test_yourkey")
payment = client.create_payment(
    body={"amount": 50000, "currency": "TZS", "description": "Order #1042"},
    idempotency_key="order-1042",
)

# CLI
bizzle login --api-key sk_test_yourkey
bizzle pay --amount 50000 --currency TZS --description "Order #1042"

Next: Authentication and Idempotency, errors & rate limits.