Skip to main content

Value Added Services & Biller Collections

Handle provides a unified, provider-abstracted Value Added Services (VAS) and Remita Retrieval Reference (RRR) Biller Collection platform. It enables merchants and client applications to vend utility tokens, purchase airtime/data, and collect government & biller payments directly.

Environments & Base URLs

All requests require the secretKey header to authenticate.

Authentication Header


4-Step Transaction Lifecycle

1

Discovery

Call GET /vending/categories, GET /vending/providers, or GET /vending/products to fetch available billers, packages, and tariff structures.
2

Validation (Required for Electricity & Cable TV)

Call POST /vending/validate with the customer’s meter or smartcard number and biller productCode. This verifies the customer’s name, address, and account status before taking payment.
3

Execution

Call POST /vending/transactions with your unique clientReference, productCode, amount, and recipient details.
4

Requery & Token Confirmation

If the network times out or returns PENDING (03), call GET /vending/query-transaction/{reference} to retrieve the final status, 20-digit token, and units without double-charging.

Status Codes Reference