Quickstart

From an API key to a completed payout and its webhook, in about five minutes on sandbox.

Everything below runs against the sandbox — simulated rails, no real money. When it works, the same calls run on production with a live key.

1. Get a sandbox key

   In the dashboard, go to Developers → API keys and create a key with the payouts:write, recipients:write, and balances:read scopes. You’ll see sk_test_… once — copy it now.

   export CHIPPER_KEY=sk_test_...
   export CHIPPER_API=https://sandbox-api.platform.chipper.ai
   
2. Fund your sandbox balance

   Payouts debit a balance. Sandbox lets you conjure one:

   curl $CHIPPER_API/v1/simulations/fund-balance \
     -H "Authorization: Bearer $CHIPPER_KEY" \
     -H "Content-Type: application/json" \
     -d '{"amount": 1000, "currency": "GHS", "externalReference": "qs-fund-1"}'
   
3. Look up what you can send to

   The capabilities catalog is the vocabulary for everything else — every code in the API comes from it.

   curl "$CHIPPER_API/v1/capabilities/GH" -H "Authorization: Bearer $CHIPPER_KEY"
   

   You’ll find gh_mtn (MTN Mobile Money) with its fields, limits, and expected settlement time.

4. Validate the destination

   Resolve the account holder’s name before moving money — the cheapest mistake you’ll ever catch.

   curl $CHIPPER_API/v1/validate \
     -H "Authorization: Bearer $CHIPPER_KEY" \
     -H "Content-Type: application/json" \
     -d '{"code": "gh_mtn", "accountNumber": "233559630374"}'
   

   { "validation": { "valid": true, "accountName": "AMA SERWAA" } }
   
5. Send the payout

   curl $CHIPPER_API/v1/payouts \
     -H "Authorization: Bearer $CHIPPER_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "to": {
         "code": "gh_mtn",
         "accountNumber": "233559630374",
         "amount": 150,
         "currency": "GHS",
         "recipient": { "name": "Ama Serwaa" }
       },
       "narration": "Invoice 1042",
       "externalReference": "inv-1042"
     }'
   

   The response is 201 with the payout in pending. Sandbox completes it within seconds — poll GET /v1/payouts/{id}, or better:

6. Receive the webhook

   Add an endpoint under Developers → Webhooks (or POST /v1/webhooks/endpoints) subscribed to payout.completed. You’ll get:

   {
     "event": "payout.completed",
     "data": { "id": "pay_ghs_…", "status": "completed", "externalReference": "inv-1042", "…": "…" }
   }
   

   Verify the signature with any Standard Webhooks library, and you’re done.

Where to next

The rails

Mobile money, bank, stablecoins — how each actually moves money.

Accept payments

Charges, virtual accounts, and deposit addresses — when to use which.

Payment links

Charge anyone with a URL and a hosted checkout.

Sandbox

Deterministic failures, simulations, and what’s mocked.