Getting Started

From zero to your first paid order

Onboarding, authentication, and a complete first payment — create, redirect, confirm — in five steps. Everything here runs in test mode; switching to live is changing one key.

1 · Get onboarded

Merchant accounts are created by the platform team (KYC is required by InnBucks compliance). You provide:

• Business details — name, type (school, hospital, retail, fleet, online, tuck shop, agent), address, business registration number.
• Contact person — name, email, phone, national ID.
• Payout wallet — the InnBucks-registered phone number your earnings should be paid to. The platform verifies the registered holder name against your national ID before payouts are enabled.

You receive back: a dashboard login (email + password) and your first test API key. Live keys are issued once your account is activated.

2 · API keys & authentication

Every API call carries your secret key as a bearer token:

curl https://omniway.online/v1/me \
  -H "Authorization: Bearer sk_test_..."

3 · Create your first payment

curl https://omniway.online/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-attempt-1" \
  -d '{
    "amount_cents": 1050,
    "currency": "USD",
    "narration": "Order #42",
    "merchant_ref": "order-42",
    "success_url": "https://yourshop.example/thanks",
    "cancel_url": "https://yourshop.example/cart"
  }'

Response (trimmed):

{
  "id": "7303405f-e518-43fe-9535-b8753349a938",
  "object": "payment",
  "livemode": false,
  "status": "pending",
  "amount_cents": 1050,
  "currency": "USD",
  "fee_cents": 16,
  "code": "820614925",
  "qr_png_data_url": "data:image/png;base64,…",
  "deep_link": "zw.co.innbucksnova.test://purchase?paymentToken=820614925",
  "ussd": "*569#",
  "checkout_url": "https://omniway.online/checkout/7303405f-…",
  "expires_at": "2026-06-11T12:13:13.000Z"
}

4 · Send the customer to pay

Redirect to checkout_url. The hosted page shows the InnBucks-branded code, QR, deep link and USSD instructions, polls for settlement, and bounces the customer back to your success_url?payment_id=… the moment the money lands. Prefer to render payment yourself (kiosk, till screen)? Use code / qr_png_data_url directly — see Payments → counter & kiosk.

5 · Confirm before you fulfil

Never trust the redirect alone — confirm server-side:

curl https://omniway.online/v1/payments/7303405f-… \
  -H "Authorization: Bearer sk_test_..."
# → "status": "paid"

Or skip polling entirely and let us push to you — register a webhook and act on payment.paid.

The same flow in Node

const POS = "https://omniway.online";
const KEY = process.env.POS_SECRET_KEY;

async function createPayment(order) {
  const res = await fetch(`${POS}/v1/payments`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `order-${order.id}`,
    },
    body: JSON.stringify({
      amount_cents: order.totalCents,
      currency: "USD",
      merchant_ref: String(order.id),
      success_url: `https://yourshop.example/orders/${order.id}/thanks`,
    }),
  });
  const payment = await res.json();
  if (payment.error) throw new Error(payment.error.message);
  return payment.checkout_url;   // redirect the customer here
}

Where to next