# VAS API Documentation

## Base URL

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

## Authentication

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

```http
Authorization: Bearer YOUR_API_TOKEN
```

See the [API conventions](https://simcloud.co.za/api/index.md#conventions) for IPv4, request timeouts, and retries.

## 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

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

#### Success Response

```json
{
    "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

```bash
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

```json
{
    "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

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

#### Insufficient Balance Response

```json
{
    "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

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

#### Pending Response

```json
{
    "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

```json
{
    "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. |