Getting started

This page walks you from "I have credentials" to "I just confirmed a purchase" in a few minutes. Everything else in these docs is reference material for the same flow.

1. Obtain credentials

When your organisation is onboarded (email support@scratch-power.com to start), a default OAuth client and an API integration user are provisioned automatically in your account. You can retrieve and manage all three login values yourself — sign in to the Scratch Power app and use the Administration menu.

client_id / client_secret — open Administration → Auth Clients. Your provisioned client is listed there; open it to copy the client_id. The client_secret is only shown once, so if you don't already have it, use Rotate secret to generate a fresh one and copy it immediately. More detail on Managing your client secret.

org_code — open Administration → My Organisation. The value shown as Organisation Code is what you pass as org_code on login.

Integration user (identifier + secret_pass) — your API user is created against the email address you were onboarded with. Find it under Administration → Actors: its username is your login identifier. To get (or reset) its password, open the user and trigger the password reset — a reset link is sent to that user's email and phone; follow it to set the password you'll use as secret_pass.

This applies when the API user is a separate account from the one you're signed in as. If the integration user is your own current account, reset your password from your profile instead — a reset triggered from the Actors list always delivers the link to that user's own email/phone.

You'll also need test meter numbers for staging — full list and per-scenario amounts on the Testing page.

2. Get an access token

Send a POST /v1/auth/login with the OAuth2 password grant fields:

curl

bash

curl -X POST https://api.scratchpower.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "grant_type": "password",
    "identifier": "integration-user",
    "secret_pass": "your-password",
    "org_code": "YOUR_ORG",
    "source_channel": "WEB"
  }'

The response gives you an access_token (Bearer) and a refresh_token:

200 OK

json

{
  "access_token": "eyJhbGciOi...",
  "access_in": 3600,
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOi...",
  "scope": "read write"
}

Use the access token in Authorization: Bearer <token> on every subsequent call. Refresh it with POST /v1/auth/refresh before access_in seconds elapse.

3. Find your debit account

Call GET /v1/auth/me to see your actor, role, organisation, and the accounts you can debit. Pick the account ID you want purchases to come from — most integrations only have one and can cache its ID.

4. Discover the available products

curl

bash

curl https://api.scratchpower.com/v1/vas-products \
  -H "Authorization: Bearer $TOKEN"

Response:

200 OK

json

[
  {
    "product_type": "ELECTRICITY",
    "display_name": "Electricity",
    "subscriber_id_label": "Meter Number",
    "subscriber_id_min_length": 11,
    "subscriber_id_max_length": 13,
    "subscriber_id_pattern": "^[0-9]{11,13}$",
    "subscriber_id_hint": null,
    "providers": [
      { "code": "BPC", "name": "Botswana Power Corporation" }
    ]
  }
]

The subscriber_id_* fields tell you what to show your user as a hint ("11–13 digits") and how to validate input before you make the API call.

5. Validate a purchase

curl

bash

curl -X POST https://api.scratchpower.com/v1/purchases/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_channel": "WEB",
    "language": "en-BW",
    "product_type": "ELECTRICITY",
    "provider_code": "BPC",
    "debited_account_id": 13209,
    "beneficiary_phone_number": "26771436390",
    "subscriber_identifier": "04040404040",
    "amount": 100,
    "currency": "BWP",
    "charges_on_top_flag": true
  }'

The response is a Transaction envelope describing the planned operation — total cost, charges, beneficiary name from the provider, etc. Show it to the user for confirmation.

6. Confirm

Same payload to POST /v1/purchases/confirm and the response includes the provider-issued token field. Single-token responses (the common case) carry just the bare token value:

200 OK (excerpt — single token)

json

{
  "id": 26,
  "status": "SUCCESSFUL",
  "type": "TOPUP",
  "reference": "TOP/2026/06/1871610006",
  "token": "0404 0404 0400 0000 0081",
  "electricity_units": "8.1kWh",
  "total": "BWP 103.00",
  "net": "BWP 100.00",
  "charge": "BWP 3.00"
}

Sometimes the provider issues several tokens at once (BPC's auto-key-change flow, for example). In that case token contains a | and is a list of Description: Token pairs — see Token format on the reference page for the parsing pattern.

That's the integration. The reference docs cover field-by-field detail, error handling, and the retry flow for handling timeouts.