Idempotency

All API requests must be made over HTTPS to: https://kda-turbo-web.vercel.app

What Is Idempotency?

Idempotency guarantees that submitting the same request more than once will not create duplicate transactions. This is critical for financial APIs where network retries, timeouts, or client bugs could otherwise cause double charges.

How It Works

Include an idempotencyKey field (preferably a UUID v4 string) in the body of every POST purchase request. The API will:

First Request (Succeeds)

Process the transaction normally and return the result.

Subsequent Requests (Blocked)

If the same key is received again, the API immediately returns a 400 error with "code": "CONFLICT", confirming the original transaction was already completed.

Example

First Request (Succeeds)

curl -X POST https://kda-turbo-web.vercel.app/api/services/data \
  -H "Authorization: Bearer kds_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "kds-data-mtn-sme-v1-003",
    "identifier": "08012345678",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "message": "Data Purchase purchase successful!",
  "transactionId": "KDS-DAT-YRGH1BZA-SN"
}

Duplicate Request (Blocked)

Sending the exact same request body again returns:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "This transaction has already been completed successfully."
  }
}

Best Practices

The idempotencyKey is strictly required for all purchase endpoints. Omitting it will result in a validation error.

Generate a new UUID for every distinct purchase intent. Use crypto.randomUUID() in JavaScript or uuid.uuid4() in Python.
Reuse the same UUID only when retrying a request that you believe may have failed due to a network error.

Idempotency

On this page