Whoosh Core API

Welcome to the Whoosh Innovations Pty. Core API — the integration layer for prepaid electricity vending, postpaid bill payments, and AARTO traffic fine management across South African municipalities.

All API requests must include a valid API key in the X-API-KEY request header.

X-API-KEY: your-api-key-here

If the header is missing or the key is invalid, the API returns HTTP 401 Unauthorized.

Important: Your test environment API key is different from your production API key. Never use a production key against a test environment.

Prepaid token vending for the following municipalities:

1. Confirm the meter — call POST /v2/Electricity/ConfirmCustomer with the meter number and municipality to validate the meter and retrieve customer details. This step is recommended before every purchase to confirm that you are vending for the correct meter.

2. Purchase — call POST /v2/Electricity/Purchase with the confirmed meter number, municipality, amount, and payment method to make the actual token purchase.

3. Monitor your balance — call POST /v1/Merchant/CheckBalance to check your remaining merchant credit before vending.

Pass a unique idempotency string on each Purchase request. If a request fails and you need to retry, reuse the same value — the system will not generate a duplicate vend.

Query and payment services for AARTO-registered traffic infringements, supporting lookups by ID number, business registration number, or notice number.

1. Look up fines — search by ID number (ViewByIDnumber), business registration number (ViewByBusinessRegistration), or notice number (ViewByNoticeNumber). Each response includes a list of InfringementDetail objects with net amounts, vendor fees, and gross amounts.

2. Validate the payment amount — call ValidateMarkTrafficFinesAsPaid with the proposed amount. The response confirms whether the amount is correct (isCorrectAmount: true) and returns the difference if not.

3. Mark as paid — call MarkTrafficFineAsPaid to declare that the merchant received the gross amount from the customer and to clear the fines with AARTO. The response includes AARTO receipt numbers (receiptNumber) and invoice numbers (invoiceNumber) per fine.

Every fine exposes three amounts:

When calling MarkTrafficFineAsPaid, submit the grossAmnt as the amount per fine.

Post paid bill payments for the following municipalities:

1. Confirm the meter — call POST /v2/Bills/ConfirmCustomer with an account number and municipality to validate the account and retrieve customer details. This step is recommended before every purchase to confirm that you are clearing debts for the correct account.

2. Purchase — call POST /v2/Bills/Purchase with the confirmed account number, municipality, amount, and payment method to make the actual debt clarrenca

Airtime, data bundles, lotto, and other value-added services. The Whoosh VAS API integration split into three simple operations: list products, confirm a quote, and purchase.

1. List products — call GET /v1/VAS/Products to retrieve the full product catalogue. Each product includes an id (use as productID) and a reference array (pass as-is in subsequent calls).

2. Confirm — call POST /v1/VAS/Confirm with the productID, amount, and reference to get a quote. The response includes the fee breakdown, total amount, and optionally a quoteId to bind to the purchase.

3. Purchase — call POST /v1/VAS/Purchase with the same fields. For airtime and data products, value is delivered directly to the recipient. For voucher products, a pin and instructions are returned to present to the customer.

Order creation and Mastercard Hosted Checkout payment initiation. Creates an order on the Whoosh platform and returns a payment URL to redirect customers for secure card capture.

1. Create an order — call POST /v1/putOrderV2 with your merchantId, order details, line items, and redirect URLs.

2. Redirect the customer — use the paymentPageUrl from the response to send the customer to the Mastercard Hosted Checkout page for secure card capture.

3. Handle the redirect — after payment, Mastercard redirects the customer to your redirectSuccess or redirectCancel URL. Use the Whoosh Reconciliation endpoints to verify the final payment status.

Staging environment: Always use merchantId: staging when calling the test base URL. A production merchantId will be issued before go-live.

MPGS reconciliation and payment status verification. Retrieve end-of-day transaction ledgers and verify the payment status of individual orders.

1. End-of-day ledger — call POST /v1/whooshEndOfDayLedgerV2 (no request body required) to retrieve all MPGS transactions for the previous South Africa business day, including totals and any verification errors.

2. Check order payment status — call POST /v1/whooshCheckOrderPaymentStatusV2 with an orderId to verify the payment status of a specific order.

The reconciliation endpoints return different response shapes depending on the HTTP status code:

{
  "success": true,
  "data": { ... },
  "error": null,
  "errorNo": null
}

success is a boolean.

{
  "success": 1,
  "result": { ... },
  "error": null
}

success is an integer — 1 for success, 0 for error.

When a Traffic Fine request fails (success: 0), the error field contains an ErrorMessage object:

{
  "success": 0,
  "error": {
    "code": 9,
    "message": "No infringement found for the provided ID number.",
    "validationMessage": []
  }
}