Collections

Take a payment from your customer's EcoCash, OMari or InnBucks into your Xash balance.

• Collections are free.
• Collected money is spend-only: it buys Xash products, and can't be withdrawn.

Start a collection

curl -s https://partners.xash.co.zw/api/v1/collections \
  -H "Authorization: Bearer $XASH_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"method":"ecocash","amount":"5.00","customer_phone":"263000000001","reference":"INV-2001"}'

It answers 202 pending with next_action, which tells you what happens next:

Method	next_action.type	What to do
ecocash	approve_on_phone	Your customer approves the prompt with their PIN. Wait.
omari	submit_otp	Ask your customer for the OTP they received, then POST /collections/{id}/confirm with {"otp": "…"}.
innbucks	pay_code	Show your customer next_action.code. They pay it in the InnBucks app.

When the customer pays, the collection becomes completed, the amount is added to your balance, and you get a collection.completed webhook. Unpaid collections fail with EXPIRED after 15 minutes.

Paying in ZWG

Send "currency": "ZWG" to let your customer pay in ZWG. They're charged at Xash's published rate (charge_amount, rate), and you're credited the USD amount.

Sandbox only for now

Live collections are in USD at launch. A live ZWG request answers 409 COLLECTION_METHOD_UNAVAILABLE with error.reason: zwg_not_live.

Reversals

If a provider reverses a payment after it completed, the amount is taken back from your balance, even if that takes it below zero. A negative balance pauses sales and collections in that environment (403 PARTNER_PAUSED) until you top up. You get collection.reversed and partner.paused webhooks.

Limits

Live collections are capped per collection and per day by your tier; see Going live.