ScratchPower Developers

Build prepaid utility purchases — electricity, airtime, water — into your own product over a small, well-documented HTTP API.

Two API surfaces

Scratch Power exposes two parallel public APIs. Both are supported; which one to use depends on whether you're already integrated.

v1 (recommended)

Lives at https://api.scratchpower.com/v1/*. Tightened request/response shapes versus the Current API, plus first-class endpoints for accounts (balances embedded) and a generic VAS purchase API that covers electricity, airtime, and water — not just electricity.

→ Read the v1 reference

Current API (deprecated)

Unversioned. Lives at hosts like https://api.scratchpower.com/auth/* and https://api.scratchpower.com/api/topup/*. Documented in our original integration PDF. Frozen — wire format and field names will not change, but no new endpoints, products, or providers will be added here. Existing integrations don't need to migrate.

→ Read the Current API reference

What you can do

Both APIs cover the essentials of running a vending integration:

• Authenticate — exchange your client credentials and integration user for a short-lived access token via OAuth2.
• Discover accounts — find the wallet to debit for each transaction.
• Validate a purchase — pre-flight: verify the meter / subscriber with the provider, see charges, surface owner details to your user.
• Confirm a purchase — actually buy the units and receive the provider-issued token(s).
• Retry a failed purchase — recover safely from timeouts without double-charging.

The v1 surface adds:

• Accounts with balances — GET /v1/accounts returns balance embedded on each account, no extra round-trip.
• VAS product discovery — GET /v1/vas-products describes the subscriber-ID format (label, length range, regex, hint) per product so you can validate input before posting.
• Generic purchases — POST /v1/purchases/* works for electricity, airtime, water; the Current API's /api/topup/* is electricity-only.

Hosts

All examples in these docs target production; swap the host for staging while you build.

Getting credentials

To request integration credentials, email support@scratch-power.com. You'll receive:

1. OAuth client_id + client_secret
2. An organisation code
3. An integration user (username + password)
4. Test meter numbers for use against staging

The same credentials work for both Current and v1.

If you ever lose your client secret or need to rotate it, head to Managing your client secret. The full list of test meters — and which one triggers which response — is on the Testing page.