Quickstart

Make your first sandbox sale in about 10 minutes. Sandbox keys never move real money.

Using an AI coding agent?

Give it INTEGRATE.md, or llms-full.txt for everything. In the portal, API keys → AI agent guide gives you the same file with a fresh sandbox key already filled in.

1. Get a sandbox key

Sign up at partners.xash.co.zw. On Home, choose Create sandbox key and copy it. You'll only see it once.

export XASH_API_KEY=xash_test_…

2. Check the key

curl -s https://partners.xash.co.zw/api/v1/me -H "Authorization: Bearer $XASH_API_KEY"

You get your partner code, "environment": "test" and the abilities this key has.

3. Find a product

curl -s "https://partners.xash.co.zw/api/v1/products?category=airtime" -H "Authorization: Bearer $XASH_API_KEY"

Each product lists required_fields (for example recipient.phone or recipient.meter) and, for fixed products, your price after discount.

4. Quote the sale

curl -s https://partners.xash.co.zw/api/v1/quotes \
  -H "Authorization: Bearer $XASH_API_KEY" -H 'Content-Type: application/json' \
  -d '{"product":"econet.airtime","amount":"5.00","recipient":{"phone":"263000000001"}}'

The quote holds the price for 5 minutes and tells you total_debit, the USD that will leave your balance. For ZESA and bills it also returns customer.name: show it to your customer first.

5. Make the sale

curl -s https://partners.xash.co.zw/api/v1/transactions \
  -H "Authorization: Bearer $XASH_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"quote_id":"qt_…","reference":"ORDER-1001"}'

• 201 means a final status. Check data.status: completed (show data.fulfilment to your customer) or failed (your money is back).
• 202 means pending. It is not a failure. Wait for the webhook, or GET /transactions/{id}.

If the call times out, send the same request with the same Idempotency-Key and reference. You get the original sale back, never a second one.

6. Try the other outcomes

Use the sandbox numbers to see a pending sale, a failure and a reversal, then set a webhook so you hear about every final status.

When your integration handles all of them, you're ready to go live.