Top-ups

Create a Taura top-up for a phone number and read the result from the returned status.

Top-up statuses

Status	What your integration should do
pending	Wait and check the top-up again before updating the customer order.
completed	Mark the customer order as successful.
failed	Read failure_reason. Use a new ref only if the customer wants another attempt.
under_review	Do not submit a duplicate. Keep the uuid and ref, and contact Xash support if needed.

Top-up fields

Field	Type	Notes
uuid	string	Taura Xashpay top-up identifier.
ref	string	Your reference for the customer request.
recipient	string	Recipient phone number.
units	number	Top-up amount in UNITS.
status	string	pending, completed, failed, or under_review.
wallet_transaction_uuid	string|null	Related wallet transaction identifier.
vendor_reference	string|null	Completion reference when available.
failure_reason	string|null	Reason supplied for an unsuccessful or reviewed top-up.
created_at	string|null	ISO 8601 timestamp.

POST/api/v1/taura/topups

Create a top-up.

Request body

Field	Type	Required	Notes
recipient	string	Yes	Phone number in E.164 format, such as +263775696233. Maximum 16 characters.
units	number	Yes	Positive amount in UNITS.
ref	string	Yes	Your unique reference. Maximum 120 characters.

Use the same ref for the same request

If you retry the same customer request, send the same ref. The API returns the existing top-up instead of creating another one. Use a new ref only for a new customer request.

Example request

curl --request POST "https://taura.xashpay.com/api/v1/taura/topups" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer TOKEN" \
  --data '{
    "recipient": "+263775696233",
    "units": 25.00,
    "ref": "ORDER-10045"
  }'

Response: 201

{
  "topup": {
    "uuid": "2236170a-85fb-4354-ab0b-941871ecfab0",
    "ref": "ORDER-10045",
    "recipient": "+263775696233",
    "units": 25.0,
    "status": "completed",
    "wallet_transaction_uuid": "9cbce09d-0d13-4cad-a7aa-537f51f5ef23",
    "vendor_reference": "TXN-10045",
    "failure_reason": null,
    "created_at": "2026-08-31T08:20:00+00:00"
  }
}

Always branch on status. Do not treat HTTP 201 alone as confirmation that the top-up completed.

Request errors

• HTTP 422 means a request field is invalid or the wallet balance cannot cover the amount.
• HTTP 429 means the rate limit was reached. Wait for Retry-After, then retry with the same ref.

See Errors for the response format.

GET/api/v1/taura/topups

List your top-ups, newest first.

Query parameters

Parameter	Type	Required	Notes
per_page	integer	No	Default 20.
page	integer	No	Page number, starting at 1.

Example request

curl "https://taura.xashpay.com/api/v1/taura/topups?per_page=20" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer TOKEN"

The response contains a topups array. Each item uses the fields listed in Top-up fields. Request the next page with ?page=2. An empty array means that page has no records.