Skip to content

Whoosh Payments

Order creation and Whoosh Payment Gateway checkout 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.

Operations

Create Order

Request

Creates an order on the Whoosh platform and returns a Whoosh Payment Gateway hosted checkout URL to redirect the customer to for secure card payment.

Whoosh orchestrates order creation and reconciliation, and the Whoosh Payment Gateway 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.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
merchantIdstringrequired

Identifies the merchant creating the order. Use staging for the test environment. A production merchantId will be issued before go-live.

Example:"staging"
orderobject(OrderDto)required

Commercial transaction details for the order being submitted for payment.

redirectSuccessstring, (uri)required

URL the customer is redirected to after a successful payment. Maps to successUrl in the Whoosh Payment Gateway.

Example:"https://placeholder.com"
redirectCancelstring, (uri)required

URL the customer is redirected to after cancellation or failure. Maps to cancelUrl in the Whoosh Payment Gateway.

Example:"https://placeholder.com"
platformstring or null

Source platform identifier used for reconciliation reporting.

Example:"MOG"
metadataobject or null

Arbitrary key-value pairs stored by Whoosh for reporting. Not forwarded to the Whoosh Payment Gateway.

Example:
{
  "orgId": "TEST-ORG-001",
  "userId": "JABS78t8ABK"
}
curl -i -X POST \
  https://docs.amabills.co.za/_mock/openapi/v2/putOrder \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "merchantId": "staging",
    "order": {
      "id": "TRF-20240215-001",
      "refferer": "TRF-20240215-001",
      "date": "2024-02-15T10:30:00Z",
      "dueDate": "2024-02-15T10:30:00Z",
      "orderDescription": "Municipal Bill Payment",
      "orderTotal": 2450,
      "vatTotal": 0,
      "currency": "ZAR",
      "products": [
        {
          "id": "MOG-123456",
          "productId": "municipal-bill",
          "name": "Municipal Bill Payment",
          "description": "Municipal bill payment for MOG-123456 of amount 1200",
          "unitPrice": 1200,
          "lineTotal": 1200,
          "vatAmount": 0,
          "currency": "ZAR",
          "quantity": 1
        },
        {
          "id": "MOG-654321",
          "productId": "municipal-bill",
          "name": "Municipal Bill Payment",
          "description": "Municipal bill payment for MOG-654321 of amount 1250",
          "unitPrice": 1250,
          "lineTotal": 1250,
          "vatAmount": 0,
          "currency": "ZAR",
          "quantity": 1
        }
      ]
    },
    "redirectSuccess": "https://placeholder.com",
    "redirectCancel": "https://placeholder.com",
    "platform": "MOG",
    "metadata": {
      "orgId": "TEST-ORG-001",
      "userId": "JABS78t8ABK"
    }
  }'

Responses

Order created successfully. Redirect the customer to paymentPageUrl.

Bodyapplication/json
orderIdstring

Internal Whoosh order ID.

Example:"whoosh-order-abc123"
referredIdstring

Vendor's original order ID (echoed back).

Example:"TRF-20240215-001"
paymentPageUrlstring, (uri)

Whoosh Payment Gateway hosted checkout URL to redirect the customer to for payment.

Example:"https://payments.whoosh.example.com/pay/abc123"
successCallbackstring, (uri)

Final success redirect URL.

Example:"https://placeholder.com"
failCallbackstring, (uri)

Final failure redirect URL.

Example:"https://placeholder.com"
Response
{
  "orderId": "whoosh-order-abc123",
  "referredId": "TRF-20240215-001",
  "paymentPageUrl": "https://payments.whoosh.example.com/pay/abc123",
  "successCallback": "https://placeholder.com",
  "failCallback": "https://placeholder.com"
}