How to Integrate Checkers Vouchers with the SIMcloud API

The SIMcloud VAS API can fetch the live voucher catalogue, select Checkers, queue one voucher purchase and return the completed voucher details after asynchronous processing. This is the correct integration path for rewards, grocery support, loyalty and customer-service applications.

Understand the Checkers API flow

1. Fetch the active VAS catalogue.
2. Find the product whose returned slug is checkers.
3. Validate the requested amount against its available_amounts.
4. Check programme approval and wallet readiness.
5. POST one voucher order with a unique reference.
6. Persist order_id and transaction_id.
7. Poll until the order is successful or failed.
8. Protect and deliver the successful voucher details.

Fetch and resolve Checkers

GET https://simcloud.co.za/api/vas.php
Authorization: Bearer YOUR_API_TOKEN

<?php

$catalogue = simcloudRequest('GET', '/api/vas.php');
if ($catalogue['http_status'] !== 200) {
    throw new RuntimeException('Could not load voucher catalogue');
}

$checkers = null;
foreach ($catalogue['body']['products'] ?? [] as $product) {
    if (($product['slug'] ?? '') === 'checkers') {
        $checkers = $product;
        break;
    }
}

if ($checkers === null) {
    throw new RuntimeException('Checkers is not currently available');
}

Validate the voucher request

$amount = 100.00;
$availableAmounts = array_map('floatval', $checkers['available_amounts'] ?? []);

if (!in_array($amount, $availableAmounts, true)) {
    throw new InvalidArgumentException('Requested Checkers amount is unavailable');
}

$reference = 'GROCERY-REWARD-000184';

Also validate local approval, recipient eligibility, budget and duplicate reference before creating value. Keep recipient personal information in your application rather than embedding it unnecessarily in the SIMcloud reference.

Create the Checkers order

$order = simcloudRequest('POST', '/api/vas.php', [
    'product_id' => (int) $checkers['product_id'],
    'amount' => $amount,
    'reference' => $reference,
]);

if ($order['http_status'] !== 201) {
    $message = (string) ($order['body']['message'] ?? 'Voucher order failed');
    throw new RuntimeException($message);
}

$orderId = (int) $order['body']['order_id'];
$transactionId = (string) $order['body']['transaction_id'];

// Persist both IDs, the local reference and current statuses now.

A 201 response means the order was queued. It does not mean the voucher code is already available.

Poll the existing order

$result = simcloudRequest(
    'GET',
    '/api/vas.php?order_id=' . rawurlencode((string) $orderId)
);

if ($result['http_status'] === 404) {
    throw new RuntimeException('Voucher order not found for this account');
}

$status = (string) ($result['body']['status'] ?? 'unknown');

if ($status === 'pending') {
    // Schedule another bounded poll.
} elseif ($status === 'success') {
    $vouchers = $result['body']['vouchers'] ?? [];
    // Store voucher details in a protected delivery store.
} elseif ($status === 'failed') {
    // Close the local order as failed and alert the responsible operator.
}

Secure the voucher code

The successful response can contain voucher type, voucher code, value and expiry information. Treat that payload differently from normal API metadata:

• Do not log the full successful response.
• Encrypt stored voucher details where appropriate.
• Restrict reads to the delivery function and authorised support.
• Do not include codes in analytics or reconciliation exports.
• Verify recipient identity before revealing the code.
• Record delivery separately from supplier completion.

Handle API errors

Frequently asked questions