API Docs / VAS

VAS API Documentation

Base URL

https://simcloud.co.za/api/vas.php

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

How It Works

  1. Call GET without query parameters to fetch the active VAS product catalog.
  2. Submit one voucher purchase request with POST.
  3. SIMcloud queues the order and returns an order_id and transaction_id.
  4. Poll the same endpoint with GET until the status changes from pending to success or failed.
  5. When the order completes successfully, the response includes the voucher code details.

Endpoints

1. List VAS Products

GET

Returns active VAS products currently available from the supplier.

Example Request

GET https://simcloud.co.za/api/vas.php

Success Response

{
    "status": "success",
    "service": "vas",
    "count": 2,
    "products": [
        {
            "product_id": 12,
            "voucher_type": "Checkers",
            "slug": "checkers",
            "default_amount": 100,
            "available_amounts": [50, 100, 200, 500],
            "logo_url": "https://simcloud.co.za/img/vas_logos/checkers.jpg"
        }
    ]
}

2. Place VAS Order

POST Content-Type: application/json

Request Parameters

Parameter Type Required Description
product_id integer No SIMcloud VAS product ID returned by the catalog endpoint.
voucher_type string No Exact voucher type or slug returned by the catalog endpoint. Required if product_id is not supplied.
amount number Yes Voucher amount in rand. Must match one of the product's available amounts.
reference string Yes Your own reference for the order. Maximum 200 characters.

The API also accepts product or voucher_supplier as aliases for voucher_type, and user_reference or client_reference as aliases for reference.

Example Request

{
    "product_id": 12,
    "amount": 100.00,
    "reference": "INV-10045"
}

Success Response

{
    "status": "success",
    "message": "VAS order queued successfully",
    "service": "vas",
    "order_id": 501,
    "transaction_id": "56b8998d-0fc6-4f63-9e02-13a52ff909f4",
    "product_id": 12,
    "voucher_type": "Checkers",
    "amount": 100,
    "fee": 0,
    "total_billed_amount": 100,
    "reference": "INV-10045",
    "process_status": "Pending",
    "billing_status": "pending",
    "timestamp": "2026-06-24 14:30:00"
}

Invalid Amount Response

{
    "status": "error",
    "message": "Amount is not available for this VAS product",
    "available_amounts": [50, 100, 200, 500]
}

Insufficient Balance Response

{
    "status": "error",
    "message": "Insufficient balance. Please top up your account.",
    "required_balance": 100,
    "available_balance": 40
}

3. Query VAS Order

GET

Poll an API-created VAS order by SIMcloud order ID or transaction ID.

Query Parameters

Parameter Type Required Description
order_id integer No SIMcloud VAS order ID returned by the POST request.
transaction_id string No Transaction ID returned by the POST request.

At least one query parameter is required to query an order. Without query parameters, GET returns the catalog.

Only VAS orders created through the API and owned by the authenticated account can be queried here.

Example Request

GET https://simcloud.co.za/api/vas.php?order_id=501

Pending Response

{
    "status": "pending",
    "message": "VAS order is still processing.",
    "service": "vas",
    "order_id": 501,
    "transaction_id": "56b8998d-0fc6-4f63-9e02-13a52ff909f4",
    "product_id": 12,
    "voucher_type": "Checkers",
    "amount": 100,
    "fee": 0,
    "total_billed_amount": 100,
    "reference": "INV-10045",
    "process_status": "Submitted",
    "billing_status": "pending",
    "supplier_http_status": 200,
    "supplier_error": null,
    "created_at": "2026-06-24 14:30:00",
    "submitted_at": "2026-06-24 14:30:20",
    "completed_at": null,
    "updated_at": "2026-06-24 14:30:20"
}

Successful Response

{
    "status": "success",
    "message": "VAS order completed successfully.",
    "service": "vas",
    "order_id": 501,
    "transaction_id": "56b8998d-0fc6-4f63-9e02-13a52ff909f4",
    "product_id": 12,
    "voucher_type": "Checkers",
    "amount": 100,
    "fee": 0,
    "total_billed_amount": 100,
    "reference": "INV-10045",
    "process_status": "Completed",
    "billing_status": "billed",
    "supplier_http_status": 200,
    "supplier_error": null,
    "created_at": "2026-06-24 14:30:00",
    "submitted_at": "2026-06-24 14:30:20",
    "completed_at": "2026-06-24 14:31:00",
    "updated_at": "2026-06-24 14:31:00",
    "vouchers": [
        {
            "voucher_type": "Checkers",
            "voucher_code": "1234567890123456",
            "value": 100,
            "expiry_date": "2029-06-24 00:00:00"
        }
    ]
}

Statuses

Error Codes

Code Description
400 Bad Request (missing or invalid parameters, unavailable denomination, or insufficient balance)
401 Unauthorized (invalid or missing token)
404 Order not found
405 Method not allowed