Claim Verification

After claim creation, the voucher owner receives a 6-digit OTP. Submit that OTP to verify and finalize the claim.

Flow

Endpoint

POST /merchant-api/claims/:id/verify

Headers

Header	Required	Description
X-API-Key	Yes	Merchant API credential.
X-Timestamp	Yes	ISO timestamp used for signature verification.
X-Signature	Yes	Base64 Ed25519 signature for the request.
Idempotency-Key	Yes	Required idempotency key for safe retries.
X-Correlation-Id	No	Optional correlation id for multi-step tracing.
User-Agent	No	Optional client identifier.

Path Parameters

Parameter	Type	Required	Rules
id	number	Yes	Positive integer claim id.

Request Body

Field	Type	Required	Rules
otp	string	Yes	Exactly 6 digits.

Example Request

curl -X POST "$API_BASE_URL/merchant-api/claims/7721/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MERCHANT_API_KEY" \
  -H "X-Timestamp: 2026-04-29T12:00:00.000Z" \
  -H "X-Signature: $MERCHANT_SIGNATURE" \
  -H "Idempotency-Key: 3323184b-9530-40bc-8cca-b90ae7bb7fa8" \
  -H "X-Correlation-Id: red_01HWJ9S8E4Y9G7E4F6N5Q2P3Z8" \
  -d '{
    "otp": "123456"
  }'

Completed Response

{
  "status": "COMPLETED",
  "redemption": {
    "id": 9801,
    "redeemedAmount": "50.00",
    "telebirrRef": "TB-240427-000125",
    "voucherRemainingBalance": "300.00",
    "voucherOriginalAmount": "500.00",
    "redeemedAt": "2026-04-27T08:03:24.000Z"
  }
}

Failed Response

{
  "status": "FAILED",
  "failure": {
    "reason": "Invalid or expired OTP.",
    "stage": "OTP_VERIFICATION"
  }
}

Response Codes

Code	Meaning
200	Claim verification processed.
400	Invalid payload, invalid claim id, missing/invalid required header, or OTP validation failure.
401	Missing or invalid auth/signature headers.
403	Access is forbidden, including IP allowlist failures.
404	Claim or voucher not found.
409	Idempotency conflict or request with same key already in progress.
503	Settlement is still in progress. Retry after a short delay.
500	Unexpected processing error.

Failure Handling

When status is FAILED, the response includes:

• failure.reason for operator-readable details
• failure.stage to identify failure point (OTP_VERIFICATION, WALLET_RESERVATION, TELEBIRR_SETTLEMENT)