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

See the API conventions for IPv4, request timeouts, and retries.

How It Works

Call GET without query parameters to fetch the active VAS product catalog.
Submit one voucher purchase request with POST.
SIMcloud queues the order and returns an order_id and transaction_id.
Poll the same endpoint with GET until the status changes from pending to success or failed.
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

curl -4 -sS -i 'https://simcloud.co.za/api/vas.php' \
  -H "Authorization: Bearer $SIMCLOUD_API_TOKEN"

Success Response

{
    "status": "success",
    "service": "vas",
    "count": 2,
    "products": [
        {
            "product_id": 12,
            "voucher_type": "Checkers",
            "slug": "checkers",
            "default_amount": 100,
            "available_amounts": [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

curl -4 -sS -i -X POST 'https://simcloud.co.za/api/vas.php' \
  -H "Authorization: Bearer $SIMCLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "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

curl -4 -sS -i 'https://simcloud.co.za/api/vas.php?order_id=501' \
  -H "Authorization: Bearer $SIMCLOUD_API_TOKEN"

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

pending: Order is queued, submitted, or being reconciled with the supplier.
success: Order completed and voucher details are available.
failed: The supplier or local processing returned a failed status.

Error Responses

VAS errors use status: error and message. An unavailable denomination adds available_amounts. Balance prechecks also return required_balance and available_balance.

HTTP Status	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
500	Could not confirm the order. Check for the original request.
503	Unable to verify the balance for a VAS order.