Endpoints

Base URL: https://partners.xash.co.zw/api/v1. Send Authorization: Bearer <key> and JSON bodies. Full schemas: openapi.json.

Account

Method	Path	What it does	Ability
GET	/me	Who am I. Your partner, the environment this key is for, your tier, abilities and how much of each limit is used today.	any
GET	/balances	Balance. Available and reserved balance in USD.	balance:read
GET	/statement	Statement. Ledger entries (top-ups, sales, collections, releases, reversals) with the running balance, newest first. Pages of up to 100; pass meta.next_cursor as ?cursor= for the next page.	balance:read

Catalogue

Method	Path	What it does	Ability
GET	/products	List products. Everything you can sell, with your price, limits and the recipient fields each product needs. Filter with category, operator and currency.	catalogue:read
GET	/products/{code}	One product. A single product by its code, e.g. econet.airtime.	catalogue:read
POST	/lookups/mobile	Identify a phone number. Returns the operator for a phone number and the products you can sell to it.	catalogue:read
GET	/branches	List branches. Your branches, for tagging sales and collections.	catalogue:read

Sales

Method	Path	What it does	Ability
POST	/quotes	Quote a sale. Step 1 of every sale. Validates the recipient (meter name, biller account) and returns the price, fee and total debit. Quotes last 5 minutes.	transactions:write
POST	/transactions	Make a sale. Step 2: spend a quote. 201 means it reached a final status (check data.status: completed or failed). 202 means pending: wait for the webhook or GET it, and never buy again. Replaying the same reference and Idempotency-Key returns the original sale with 200 and Idempotency-Replayed: true. Needs Idempotency-Key.	transactions:write
GET	/transactions	List or find sales. Filter by reference, status, branch_id, from and to.	transactions:read
GET	/transactions/{id}	One sale. The authoritative status of a sale, with the token or PIN and receipt data once completed.	transactions:read

Collections

Method	Path	What it does	Ability
POST	/collections	Collect from a customer. Starts an EcoCash, OMari or InnBucks payment from your customer into your balance. Usually 202 pending; next_action says what happens next. Collections are free, and the money is spend-only: it can only buy Xash products. Replays return 200 with Idempotency-Replayed: true. Needs Idempotency-Key.	collections:write
POST	/collections/{id}/confirm	Confirm an OMari collection. Submit the OTP your customer received.	collections:write
GET	/collections	List or find collections. Filter by reference, status, method, branch_id, from and to.	collections:read
GET	/collections/{id}	One collection. The authoritative status of a collection.	collections:read

Top-ups

Method	Path	What it does	Ability
POST	/fundings	Top up by mobile money or USDT. Starts a top-up of your own balance. Bank transfers are matched by Finance using your partner code as the payment reference. Needs Idempotency-Key.	funding:write
GET	/fundings/{id}	One top-up. The status of a top-up.	funding:write

Webhooks

Method	Path	What it does	Ability
POST	/webhooks/test	Send a test event. Sends a signed webhook.test event to this environment's webhook URL now and tells you what your endpoint answered. Use it to check your signature verification.	any