How to Build an Employee Rewards Platform with the Voucher API

A useful employee rewards platform does more than issue gift codes. It controls eligibility, approval, catalogue selection, wallet availability, voucher fulfilment, private delivery and reconciliation. The SIMcloud VAS API supplies the catalogue and voucher-order lifecycle; your application supplies programme policy and user experience.

Design the platform boundaries

Separate six responsibilities:

Create a traceable data model

A minimal relational design needs records for programmes, recipients, approvals, reward orders and delivery. The reward order should include:

• Local reward order ID.
• Programme and employee reference.
• Approver and approval timestamp.
• Requested product slug and amount.
• SIMcloud product ID resolved from the current catalogue.
• SIMcloud order_id and transaction_id.
• Processing and billing status.
• Created, submitted, completed and delivered timestamps.
• Safe failure reason.

Store completed voucher details separately with stricter access and encryption appropriate to your environment. Do not copy them into the ordinary reward-order log.

Load the live VAS catalogue

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

The response includes current products, product IDs, voucher types, slugs and available amounts. The employee interface should offer only the products approved by your programme and currently returned by SIMcloud.

Approve before creating value

1. Create a reward request with an immutable local ID.
2. Evaluate programme eligibility and remaining budget.
3. Resolve the chosen product against the current catalogue.
4. Validate the amount against programme rules and the live product.
5. Record the approver and approval time.
6. Queue a fulfilment job; do not call SIMcloud directly from the approval-page browser request.

Submit the VAS order

POST https://simcloud.co.za/api/vas.php
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "product_id": 12,
  "amount": 100.00,
  "reference": "REWARD-2026-000184"
}

The example product ID is illustrative. Use the ID returned by the catalogue in the same integration flow.

A successful creation returns HTTP 201 with order_id, transaction_id, product, amount, fee, total billed amount, reference, processing state and billing state. Persist those fields before the worker exits.

Poll to a final result

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

Pending means queued, submitted or being reconciled. Success includes the completed voucher details. Failed is final and requires the programme’s exception process.

1. Load a pending local reward order.
2. Query using its persisted SIMcloud order ID.
3. Update processing and billing fields.
4. If pending, schedule another bounded poll.
5. If successful, store the voucher details in the protected delivery store.
6. If failed, close fulfilment and notify the responsible operator.
7. Never create a replacement automatically without reconciling the original order.

Deliver the voucher privately

The delivery service should check that the reward remains approved, the SIMcloud order is successful and the authenticated employee matches the intended recipient. A secure employee portal is preferable to email or chat where feasible.

Record delivery time and channel. Do not mark a reward “delivered” merely because the supplier issued the code.

Handle wallet and catalogue failures

Build programme reconciliation

Report approved, submitted, successful, failed and delivered reward counts and values. Match records by your immutable reference and SIMcloud IDs. Ordinary reports should not include voucher codes.

Frequently asked questions