# Xash Partners API

> Sell Xash products (airtime, data, ZESA electricity, bills) and collect EcoCash, OMari and InnBucks payments from your customers, from your own system. Base URL: https://partners.xash.co.zw/api/v1

## Rules for integrating (read these first)

1. Every sale is two calls: POST /quotes, then POST /transactions with {quote_id, reference}.
2. Send your own unique `reference` and an `Idempotency-Key` header (UUID). On a timeout, send the SAME request with the SAME key. Never make a new quote for an order that might already be sold.
3. 202 with status `pending` is NOT a failure. Wait for the webhook or GET the record.
4. Only `failed` means nothing was delivered and the money is back.
5. Verify webhooks: hex HMAC-SHA256 of "{X-Xash-Timestamp}.{raw body}" with your webhook secret; reject if older than 5 minutes; dedupe by X-Xash-Event-Id.
6. Amounts are strings like "5.00" in USD. Phone numbers are 2637XXXXXXXX.
7. Sandbox keys start xash_test_ and never move real money. Live keys start xash_live_.
8. Branch on `error.code`, never on `message`.

## Statuses

- `pending`: Money is reserved and the outcome is not final yet. Never treat this as failed and never buy again; wait for the webhook or GET the record.
- `completed`: Delivered (sale) or received (collection). Final unless the provider later reverses it.
- `failed`: Definitely not delivered or not received. For a sale, the money is back in your balance.
- `reversed`: Was completed, then the provider reversed it. For a sale the money is returned; for a collection it is debited.

## Endpoints

- `GET /me`: Who am I
- `GET /balances`: Balance
- `GET /statement`: Statement
- `GET /products`: List products
- `GET /products/{code}`: One product
- `POST /lookups/mobile`: Identify a phone number
- `GET /branches`: List branches
- `POST /quotes`: Quote a sale
- `POST /transactions`: Make a sale
- `GET /transactions`: List or find sales
- `GET /transactions/{id}`: One sale
- `POST /collections`: Collect from a customer
- `POST /collections/{id}/confirm`: Confirm an OMari collection
- `GET /collections`: List or find collections
- `GET /collections/{id}`: One collection
- `POST /fundings`: Top up by mobile money or USDT
- `GET /fundings/{id}`: One top-up
- `POST /webhooks/test`: Send a test event

## Docs

- [Endpoints](https://docs.partners.xash.co.zw/reference/endpoints)
- [Errors](https://docs.partners.xash.co.zw/errors)
- [OpenAPI](https://docs.partners.xash.co.zw/openapi.json)