# Dhiraagu API Documentation

Reverse-engineered from traffic captures of the Dhiraagu Easy Pay web service (`dhiraagu.com.mv`).

---

## Overview

Dhiraagu exposes a number-lookup API used by their Easy Pay web page to validate mobile numbers before payment. The API uses a two-step flow:

1. **Nonce extraction** — fetch the Easy Pay HTML page and extract a one-time nonce token embedded in the page JavaScript.
2. **Number lookup** — POST the mobile number with the nonce to the IO API endpoint, which returns the account type and owner name.

The nonce is single-use and page-session-specific; it must be re-fetched for each lookup.

---

## Base URL

```
https://www.dhiraagu.com.mv
```

---

## Authentication Model

| Value | How obtained | How used |
|---|---|---|
| `nonce` | Extracted from Easy Pay page HTML | Sent as `nonce` request header on the lookup POST |

No persistent session or login is required. The nonce is valid for a single lookup request.

---

## Common Request Headers

```
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:150.0) Gecko/20100101 Firefox/150.0
Origin: https://dhiraagu.com.mv
```

The `User-Agent` header is required; requests without it are rejected by the server.

---

## Number Lookup Flow

```
Client                                      Server
  |                                           |
  |  GET /services/easy-pay                   |  ← fetch page to get nonce
  |----------------------------------------->|
  |  200 OK (HTML page)                       |
  |  var nonce = "feb6acb9-a532-428e-..."     |
  |<-----------------------------------------|
  |                                           |
  |  POST /api/sdk-dhr-webapi.ashx            |
  |  ?website_id=CA2BB809...                  |
  |  &sub=dhiraaguIO&act=infoUnlisted         |
  |  nonce: feb6acb9-a532-428e-...            |
  |  { "number": "7654321" }                  |
  |----------------------------------------->|
  |  { respStatus: "OK",                      |
  |    serviceDetails: [{prepaidIndicator}],  |
  |    accountOwnerInfo: { name } }           |
  |<-----------------------------------------|
```

---

## Result Interpretation

| `prepaidIndicator` | Meaning |
|---|---|
| `"Y"` | Prepaid — use **Dhiraagu Reload** |
| `"N"` | Postpaid — use **Dhiraagu Bill Pay** |
| absent / other | Number not found or unsupported |

---

## Applicable Numbers

Dhiraagu numbers in the Maldives typically start with **7**, but due to **mobile number portability (MNP)**, a subscriber may have ported their number from Ooredoo (originally a 9xxx number) to Dhiraagu — or vice versa. The number prefix alone does not reliably identify the current provider.

For this reason, both providers should be tried when looking up an unknown number:
- If the number starts with **7**, try Dhiraagu first; fall back to Ooredoo if Dhiraagu returns a failed status.
- If the number starts with **9**, try Ooredoo first; fall back to Dhiraagu if Ooredoo returns no match.

The API only returns a valid result for numbers currently on the Dhiraagu network, regardless of what prefix they carry.

---

## Documents

| # | File | Description |
|---|---|---|
| 1 | [Number Lookup](01-number-lookup.md) | Validate a Dhiraagu number and determine account type |

---

&nbsp;

---

> **Next →** [Number Lookup](01-number-lookup.md)