Seller API v1

Sell data from your own system. Create an API key in the reseller portal, then call the endpoints below. Keep your key on your server. Never put it in a website or app.

Authentication

Authorization: Bearer YOUR_API_KEY

Keys are shown once when created. Revoke a key in the portal if it is exposed.

Rate limit: 60 requests per minute per key. Responses over the limit return HTTP 429 with a Retry-After header.

Endpoints

Method	Path	Purpose
GET	`/api/v1/packages`	Bundles you can sell, with your price.
GET	`/api/v1/wallet`	Your balance and discount.
POST	`/api/v1/purchases`	Buy a bundle from your wallet.
GET	`/api/v1/purchases`	Your purchases, newest first. Use `limit` and `before_id`.
GET	`/api/v1/purchases/{id}`	One purchase and its current status.

Buy a bundle

Send a unique reference for every sale in your system (1 to 105 characters). If a request is retried with the same reference, you get the original order back and are not charged twice.

curl -X POST https://maxdata-hub.com/api/v1/purchases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"my-order-1001","bundle_id":1,"recipient":"0244123456"}'

Response, HTTP 201:

{"success":true,"message":"Purchase accepted","data":{"id":42,"reference":"my-order-1001","status":"paid",
 "network":"MTN","bundle":"1 GB","size_mb":1024,"recipient":"0244123456","amount_ghs":3.42,...}}

Errors

HTTP	error	Meaning
400	invalid_json	Body is not a JSON object.
401	missing_key, invalid_key	No key, or the key is wrong or revoked.
402	insufficient_balance	Top up your wallet, then retry with the same reference.
403	account_inactive	Your reseller account is pending or suspended.
404	not_found	Unknown endpoint, or a purchase that is not yours.
409	reference_conflict	That reference was used for a different bundle or number.
422	invalid_reference, invalid_recipient, invalid_bundle	Check the field named in the message.
429	rate_limited	Slow down. Wait for the Retry-After time.

Order statuses

Status	Meaning
`paid`	Payment taken from your wallet, waiting to be sent.
`manual`	Being delivered by hand. Usually confirmed soon.
`submitted`	Accepted by the network, waiting for delivery.
`delivered`	Delivered.
`uncertain`	We are checking the outcome. Do not resend; check again shortly.
`failed`	Could not be delivered. The amount is refunded to your wallet.
`refunded`	Refunded to your wallet.

Poll GET /api/v1/purchases/{id} to follow a purchase. Only treat an order as final at delivered, failed or refunded.

Recipients

Send local numbers as 10 digits starting with 0, for example 0244123456. Quote numbers as strings so the leading zero is kept.