# Amabills - Whoosh Core API

The Whoosh Innovations Pty. Core API provides electricity vending and traffic
fine services for South African municipalities.


## Authentication

All requests must include a valid API key in the `X-API-KEY` request header.
If the header is missing or the key is invalid, the service returns HTTP **401 Unauthorized**.

> **Note:** The API key for the test environment is different from the production API key.


## Environments

| Environment | Base URL  |
|---|---|
| Testing | `https://api-test.amabills.co.za/api` |
| Production | `https://api.amabills.co.za/api` |


## Success flag

Traffic Fine endpoints return `success` as an **integer** (`1` = success, `0` = error).
Electricity endpoints return `success` as a **boolean**.
Whoosh Reconciliation endpoints return `success` as a **boolean**.


Version: 1.1.0

## Servers

Testing
```
https://api-test.amabills.co.za/api
```

Production
```
https://api.amabills.co.za/api
```

## Security

### ApiKeyAuth

Type: apiKey
In: header
Name: X-API-KEY

## Download OpenAPI description

[Amabills - Whoosh Core API](https://docs.amabills.co.za/_bundle/openapi.yaml)

## Electricity

Prepaid token vending and postpaid bill payments for Tshwane, Mogale, and Zeerust municipalities.

### Confirm Customer

 - [POST /v2/Electricity/ConfirmCustomer](https://docs.amabills.co.za/openapi/electricity/confirmcustomer.md): Verifies that a meter number exists and is eligible for electricity vending or bill payment. Call this before purchasing to avoid higher latency — if you vend with an unknown meter number the system runs an implicit lookup first.

### Purchase / Vend Token / Pay Bills

 - [POST /v2/Electricity/Purchase](https://docs.amabills.co.za/openapi/electricity/purchaseelectricity.md): Vends an electricity token (prepaid) or marks a payment against a postpaid running balance.

- Prepaid (tshwane_prepaid, mogale_prepaid, zeerust_prepaid):
  returns a token string the customer enters into their meter.

- Postpaid (mogale_bills): returns a receipt URL proving bill offset.

Use the idempotency field to safely retry failed requests without risk of duplicate vends.

### Check Balance

 - [POST /v1/Merchant/CheckBalance](https://docs.amabills.co.za/openapi/electricity/checkbalance.md): Returns the authenticated merchant's current credit balance across all consumed prepaid VAS services. Optionally includes a transaction breakdown for a specified period.

## VAS

Value-added services (airtime, data, etc.).

### Confirm VAS

 - [POST /v1/VAS/Confirm](https://docs.amabills.co.za/openapi/vas/confirmvas.md)

### Purchase VAS

 - [POST /v1/VAS/Purchase](https://docs.amabills.co.za/openapi/vas/purchasevas.md)

## Traffic Fines

Traffic fine lookups, payment validation, and payment marking via the AARTO system.

### Query by ID Number

 - [POST /v1/TrafficFine/ViewByIDnumber](https://docs.amabills.co.za/openapi/traffic-fines/viewtrafficfinebyid.md): Returns all recorded traffic fines for a given South African national ID number.

### Query by Business Registration Number

 - [POST /v1/TrafficFine/ViewByBusinessRegistration](https://docs.amabills.co.za/openapi/traffic-fines/viewtrafficfinebybrn.md): Returns all recorded traffic fines for a given business registration number (BRN).

### Query by Notice Number

 - [POST /v1/TrafficFine/ViewByNoticeNumber](https://docs.amabills.co.za/openapi/traffic-fines/viewtrafficfinebynoticenumber.md): Returns the details of a specific traffic fine by its AARTO notice number.

### Validate Traffic Fine Payment

 - [POST /v1/TrafficFine/ValidateMarkTrafficFinesAsPaid](https://docs.amabills.co.za/openapi/traffic-fines/validatemarktrafficfinesaspaid.md): Validates that the proposed payment amount matches the expected gross amount for the selected fines. Call this before MarkTrafficFineAsPaid to confirm the correct amount.

### Mark Traffic Fines as Paid

 - [POST /v1/TrafficFine/MarkTrafficFineAsPaid](https://docs.amabills.co.za/openapi/traffic-fines/marktrafficfineaspaid.md): Marks one or more traffic fines as paid on behalf of a customer. The merchant declares that they received the gross amount (net fine + vendor fee) from the customer and wishes to clear the fines with AARTO.

Calling this endpoint will result in a Whoosh invoice for the gross transaction value of all fines marked paid, issued at the end of each billing cycle.

> Recommended: Call ValidateMarkTrafficFinesAsPaid first to confirm the correct amount before calling this endpoint.

## Whoosh Payments

Order creation and Mastercard Hosted Checkout payment initiation. Use these endpoints to create an order on the Whoosh platform and obtain a payment URL to redirect customers for secure card capture.
There also reconciliation and payment status verification endpoints. Use these to retrieve end-of-day transaction ledgers and verify the payment status of individual orders.

### Create Order

 - [POST /v1/putOrderV2](https://docs.amabills.co.za/openapi/whoosh-payments/putorderv2.md): Creates an order on the Whoosh platform and returns a Mastercard Hosted Checkout URL to redirect the customer to for secure card payment.

Whoosh orchestrates order creation and reconciliation; Mastercard manages card capture, authorization, and payment security.

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

### End of Day Ledger

 - [POST /v1/whooshEndOfDayLedgerV2](https://docs.amabills.co.za/openapi/whoosh-payments/whooshendofdayledger.md): Returns all MPGS transactions for the previous South Africa business day, including reconciliation metadata and any verification errors.

No request body is required. The merchant is identified automatically from the x-api-key header.

> Note: Response format differs by status code. 200 and 500 return a direct object; 404 returns a { status, data } wrapper.

### Order Payment Status

 - [POST /v1/whooshCheckOrderPaymentStatusV2](https://docs.amabills.co.za/openapi/whoosh-payments/whooshcheckorderpaymentstatus.md): Verifies the payment status of a specific order by checking its associated MPGS payment sessions.

> Note: Response format differs by status code. 200 and 500 return a direct object; 400 and 404 return a { status, data } wrapper.