Getting Started

Idempotency

Safely retry requests without accidentally performing the same airtime transaction twice.

Send a unique idempotency key with an intended airtime order. If a network timeout occurs, retry the same request with the same key rather than creating a new key.

How it works

cURL

curl -X POST https://api.buyairtime.co.ke/v1/airtime \
  -H "Authorization: Bearer {{token}}" \
  -H "Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Content-Type: application/json" \
  -d '{{"phone":"0712345678","amount":100,"network":"safaricom"}}'

Request-body alternative

JSON

{{"phone":"0712345678","amount":100,"network":"safaricom","idempotencyKey":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}}

If the same key is received with the same payload, the server can replay the original response without executing the transaction again.

Payload mismatch

Using the same key with a different payload should return 409 Conflict.

Generating keys

JavaScript

const idempotencyKey = crypto.randomUUID();

Python

import uuid
idempotency_key = str(uuid.uuid4())

Key lifetime

Our initial design retains idempotency keys for 24 hours.

Rules

Rule	Detail
Scope	Airtime order and other delegated transaction endpoints.
Format	Unique string up to 255 characters; V4 UUID recommended.
Mismatch	Same key with a different payload returns 409.
Expiry	Eligible for removal after 24 hours.