Testing
Before you go live, build and verify your integration against the staging environment. Staging looks and behaves exactly like production — same endpoints, same response shapes — but two things are different:
- Your sandbox wallet is pre-loaded with BWP 1,000,000.00, so you can run as many test purchases as you like without spending real money.
- Your organisation is locked to a fixed list of test meter numbers. Any real meter number is rejected. This stops accidental purchases against live BPC meters during development.
The staging base URL is:
https://api.staging.scratchpower.comThe login flow and every endpoint are otherwise identical to production — the only thing that changes is the host name.
Test meter numbers
These are the meter numbers BPC has earmarked for testing. Each one triggers a specific response so you can exercise every code path — happy path, blocked customers, multi-token vends, and so on — without needing real customer data.
| Meter number | Scenario |
|---|---|
04040404040 | Active meter — 11 digits. The default happy-path meter. |
04040404099 | Active meter that has a tariff charge applied. |
04040404107 | Active meter with a tariff charge and a sub-account split. |
04040404461 | Fixed-charge meter (BWP 1000). Tender at or below the fixed charge to exercise the minimum-vend / "amount too low" error path. |
04040404081 | Blocked customer. Validation returns a meter_blocked error. |
04040404057 | Customer whose purchases have been blocked (separate from a full account block). |
04040404065 | Customer can only purchase until their outstanding debt is paid off. |
04040404073 | Account-level transaction block (blanket block on this account). |
04240297236 | Meter not found / disconnected. |
04040404198 | Auto Key Change Token — vending here returns three tokens (KeyChange Token1, KeyChange Token2, Credit Token) pipe-separated in one token field. See Token format for the exact wire shape. Fixed charge BWP 1000. |
0404040404000 | Active meter — 13 digits. Lets you verify your input validation accepts both 11- and 13-digit meters. |
04040404305 | Delayed response (~95 s). Simulates a provider timeout — your HTTP client's read timeout will fire before the response comes back. |
04040404404 | Maximum-vend fault. Returns Purchase Amount cannot be greater than BWP 100000,00. |
If you try to validate or confirm against a meter number that isn't on this list, the platform will refuse the request — even if the number looks valid. This is a deliberate safety net so you don't accidentally fire test traffic at a real customer.
Test case scenarios
Walk through every response shape your client needs to handle.
Each row pairs a meter number with a recommended amount; running
the pair through POST /v1/purchases/validate followed by
POST /v1/purchases/confirm reproduces the named outcome.
The simulator is driven by the meter number — every meter has a single configured scenario, and most rows below produce the same response shape at any amount above the meter's fixed-charge floor. The amount only matters where the row is explicitly amount-sensitive (rows 4 & 5, where you're crossing the fixed-charge threshold).
| # | Scenario | Meter | Amount |
|---|---|---|---|
| 1 | Successful token generation | 04040404040 | BWP 100 (any > 0) |
| (alt — with tariff charge) | 04040404099 | BWP 100 (any > 0) | |
| (alt — with tariff charge + sub-account debt) | 04040404107 | BWP 100 (any > 60) | |
| 2 | Customer/meter error — blocked customer | 04040404081 | any |
| — purchases blocked | 04040404057 | any | |
| — purchase-until-debt-paid | 04040404065 | any | |
| — account block | 04040404073 | any | |
| — meter not found | 04240297236 | any | |
| 3 | Multi-token generation — token field carries 3 entries as Description: Token pairs joined by | (e.g. "KeyChange Token1: …|KeyChange Token2: …|Credit Token: …") | 04040404198 | BWP 1100 (any > 1000) |
| 4 | Minimum-vend / no-token error — tendered amount below the fixed charge | 04040404461 | BWP 10 (any ≤ 1000) |
| 5 | Successful vend on a fixed-charge meter — tendered amount clears the fixed charge | 04040404461 | BWP 1140 (any > 1000) |
| 6 | Timeout — server sleeps ~95 s; exercises the self-managed retry path | 04040404305 | any |
| 7 | Maximum-vend error — amount-too-high fault | 04040404404 | any |
Scenario 6 (timeout) is the most underrated one to test, because
timeouts are rare in dev but real in production. When a confirm call
times out, the transaction state with the provider is unknown —
it may have succeeded server-side even though your client got no
response. Use POST /v1/purchases/retry (or the legacy
POST /api/topup/retry) to ask the platform to reconcile with BPC
before you re-submit. See Errors
for the full retry handshake.
Switching to production
When you're ready to cut over:
- Confirm your staging tests cover every row in the scenarios table above — especially error and timeout flows.
- Swap the base URL to
https://api.scratchpower.com. - Use the production
client_id,client_secret, and integration user that the Scratch Power team provisioned for you (different from staging — staging credentials are not accepted in production). - The meter-number lock is lifted in production. You can now transact against any real BPC meter number a customer gives you.
If anything looks off after cutover, you can roll back by pointing your base URL at staging again — your production credentials won't work there, but the staging credentials still will, so you stay testable without a deploy.