Skip to main content
The Hyparrow sandbox is a complete, isolated copy of the API that simulates every external provider. Use it to build and test your integration end-to-end — KYC verifications, payments, transfers, bills and crypto — without moving real money or hitting real providers.

​
Base URL

All sandbox requests go to:
This is the same API surface as production (https://api.hyparrow.cloud/api/v1) — only the host and your keys differ.

​
Test API keys

The sandbox accepts test keys only. Create one from your dashboard’s API keys page while in Sandbox mode; it is minted with pk_test_ / sk_test_ prefixes and lives in the sandbox database.
Don’t see an API keys page? It lives in the Developer extension. Open Extensions in your dashboard sidebar and install Developer first — the API keys page (and the rest of the developer tools) will then appear.

Strict environment isolation

A test key only works against the sandbox, and a live key only works against production. Using a live key on the sandbox (or vice versa) returns 403 Forbidden. A test key can never move real money.
Every sandbox merchant is provisioned with a funded test wallet (₦5,000,000) so calls that bill against your balance (pay-as-you-go verifications, transfers, bill payments) succeed out of the box.

​
Magic test values

Sandbox responses are deterministic and driven by “magic” inputs, so you can reliably exercise both success and failure paths.

​
Identity verification (BVN, NIN, etc.)

The rule is applied to whichever identifier the endpoint takes — bvn, nin, vin, phone_number or rc_number.
All ones is the only special-cased value. Every other identifier succeeds, so 00000000000 returns a record like any other input — there is no separately reserved “success” value.
These magic values exist only in the sandbox. Production has no test identifiers: sending 00000000000 or 11111111111 to api.hyparrow.cloud is a live lookup, the verification network has no such record, and you get a 404 RECORD_NOT_FOUND (automatically refunded — see Identity Verification).
The sandbox failure response is byte-for-byte the shape production returns, so the branch you write here is the branch that runs live:
404 Response
A sandbox success nests the record at data.data exactly as production does — see Response envelope — but the keys of the intermediate envelope are not identical:
Sandbox success
Production carries success, statusCode, message and response_code at that level instead of status and message, and its inner record uses the verification network’s own field names (for BVN basic: phoneNumber1, phoneNumber2, image). Read the record at data.data in both environments, but do not branch on the intermediate envelope’s keys, and confirm inner field names against the production examples in Identity Verification before you go live.

​
Payments (transfers, bills, card charges, VA funding)

By default a simulated payment settles successfully. The amount’s last two minor-unit digits force the other paths:

​
Card payments

​
What’s simulated

In the sandbox, every external provider is short-circuited — no real calls are made and no real costs are incurred:
  • Identity / KYC — BVN, NIN, phone, voter’s card, CAC and account-number lookups
  • Payments — virtual accounts, money transfer, card payments
  • Bills — airtime, data, cable TV, electricity, PINs
  • Crypto — wallet creation, balances, transfers
Billing still runs against your funded test wallet, so you can observe quota, pay-as-you-go and insufficient-balance behaviour exactly as in production — just with simulated money.

​
Going live

When your integration works in the sandbox, switch your dashboard to Live mode, generate a live (pk_live_) key, and point your requests at https://api.hyparrow.cloud/api/v1. No code changes are required beyond the base URL and credentials.