From Signup to Live¶

The whole path, in order, from having no account to taking real payments. Each step links to the page that covers it in detail; this page exists so you can see where you are and what is left.

Nothing here is a waiting game except the business verification in step 3, and you can build the entire integration while that is in progress.

1. Get an account¶

Either:

• Sign up yourself at the merchant portal. You give personal and business details, verify your email address with a one-time code, and you are in. Your wallet is created at that point.
• Be onboarded by Hivemind Payments. If you spoke to us first, we create the account and email you a password. Your business is already verified in this case, so step 3 is done before you start.

You can collect payments from day one either way. Paying money out requires verification — see step 3.

2. Create sandbox credentials¶

In the portal: Developers → API Applications → Create application, environment Sandbox.

You get a client ID and secret, and a sandbox wallet with a play balance of KES 1,000 and its own account number. Use that account number as merchant_id in sandbox requests — not your live one.

That balance is small on purpose: payouts draw it down, so you will meet the wallet's own balance check early. Collections credit the same wallet, and you can reset it from the portal.

No verification, approval or support ticket is needed for this. It is available the moment you have an account.

→ Sandbox and Going Live

3. Get verified (in parallel)¶

In the portal: Settings → Compliance. Upload your business registration, ownership details and a settlement account. A Hivemind Payments reviewer checks them.

This is the only step with a human in the loop, and it is the one that unlocks payouts and live API credentials. Start it early and build against sandbox while it runs. If Hivemind Payments onboarded you directly, this is already done.

4. Build against sandbox¶

Four calls make up an integration. All of them are identical in sandbox and production — only your credentials and merchant_id differ.

1. Get a token — GET /auth/token/ with HTTP Basic auth, your client ID as the username and the secret as the password. → Authentication
2. Initiate a payment — POST /payments/initiate/ with transaction_type (C2B collection, B2C payout, B2B transfer), payment_method, amount, account_number, your own unique reference, and a result_url for us to call back on. → Initiate Payment
3. Receive the result — we POST it to your result_url when the payment reaches a final state. → Result URL Callbacks
4. Reconcile — POST /payments/status-query/ for a definitive answer on one payment, and GET /transactions/ for a statement. → Status Query, Statement

In sandbox the destination decides the outcome. account_number ending 000000 succeeds, 000001 is cancelled by the customer, 000002 is insufficient funds, 000003 never calls back at all, 000004 is an ambiguous payout, 000005 succeeds two minutes late. Work through all six — the failures are the half of the API that decides whether your integration survives production.

→ Sandbox Credentials & Test Numbers, Test Scenarios

5. Clear the go-live checklist¶

The portal shows it at Developers → Go Live, with what is outstanding:

• business verified,
• one successful sandbox collection,
• one successful sandbox payout,
• your webhook has returned a 2xx to a sandbox result,
• at least one whitelisted server IP address.

Four of the five are things you will have done anyway by finishing step 4. The webhook one is the reason the list exists: it is what catches an integration about to go live with a callback endpoint that has never actually received anything.

→ Sandbox and Going Live

6. Create production credentials¶

Same place as step 2, environment Production. They are issued as soon as the checklist passes, and refused with a list of what is outstanding if it does not.

Then change three pieces of configuration:

• the client ID and secret,
• merchant_id — your live wallet's account number, not the sandbox one,
• result_url, if your production handler is a different service.

Nothing else about your integration changes. If something else has to, tell us — that is our bug.

Your sandbox application keeps working. You now hold both, permanently. Point your staging environment at sandbox and keep testing there; you will want it for your next change.

7. After you are live¶

• IP whitelisting is enforced in production. A request from an unregistered address is refused. Add addresses in the portal as your infrastructure changes. → IP Whitelisting
• Payouts need funds in your wallet, and are only available once verified.
• Treat your secret as a secret. → Token Handling
• Keep handling the awkward results. Timeouts and ambiguous payouts happen in production too; that is why you tested them.

At a glance¶