> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudtraceai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Screen UPI Payees in Real Time Before Funds Are Transferred
> Embed FraudTrace AI into your payment flow to screen UPI VPAs for mule activity, gambling links, and fraud clusters before any money moves.
Before any rupee leaves your system, FraudTrace AI gives you a real-time signal on whether the destination UPI VPA has appeared on fraud sites, gambling platforms, or in mule account clusters. This guide walks you through embedding that check directly into your payment flow — at payee addition, before approving a transaction, or at payout — so high-risk VPAs are caught before money moves.
## Integration steps
### Identify where in your flow to call the API
Pick the earliest point in your payment flow where the destination VPA is known. Common integration points include:
* **Payee addition** — screen the VPA when a customer adds a new beneficiary. Blocking here prevents the payee from being saved at all.
* **Pre-payment approval** — screen immediately before authorising a UPI push. Suitable for P2P transfers and bill payments.
* **Payout / disbursement** — screen beneficiary VPAs before releasing payroll, cashbacks, or loan disbursals.
Screening at payee addition catches risk the earliest. Screening at payout is the last line of defence — use both where your risk appetite demands it.
### Make the API call
Send a `GET` request with the VPA as a query parameter. The API responds in under 200ms at p99, making it safe to call inline without adding perceptible latency.
```bash curl theme={null}
curl -G https://api.fraudtraceai.com/v1/verify/upi \
--data-urlencode "upi=xxxxx@ybl" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python Python theme={null}
import requests
def screen_upi(vpa: str, api_key: str) -> dict:
resp = requests.get(
"https://api.fraudtraceai.com/v1/verify/upi",
params={"upi": vpa},
headers={"Authorization": f"Bearer {api_key}"}
)
resp.raise_for_status()
return resp.json()
result = screen_upi("xxxxx@ybl", "YOUR_API_KEY")
print(result)
```
```javascript Node.js theme={null}
const apiKey = "YOUR_API_KEY";
const vpa = "xxxxx@ybl";
const url = new URL("https://api.fraudtraceai.com/v1/verify/upi");
url.searchParams.set("upi", vpa);
const response = await fetch(url.toString(), {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) {
throw new Error(`FraudTrace API error: ${response.status}`);
}
const result = await response.json();
console.log(result);
```
Response time is under 200ms at p99, making this endpoint safe for inline
screening without adding noticeable latency to your payment flow.
### Handle the response
The response contains a `status` field (`FLAGGED` or `CLEARED`) and, for flagged VPAs, a `confidence` score between 0 and 1. Use these two fields together to decide the next action.
**Flagged response example**
```json theme={null}
{
"upi": "xxxxx@ybl",
"status": "FLAGGED",
"confidence": 0.94,
"risk_category": "mule",
"cluster_id": "MC-2104",
"cluster_size": 7,
"first_seen": "2025-11-14T08:22:00Z",
"last_seen": "2026-04-01T16:45:00Z",
"sources": [
{
"url": "https://bet-quick-in.com",
"category": "gambling",
"captured_at": "2025-12-01T10:00:00Z",
"screenshot_available": true
},
{
"url": "https://spinwin-247.net",
"category": "gambling",
"captured_at": "2026-01-15T14:30:00Z",
"screenshot_available": true
}
],
"evidence_count": 3
}
```
**Cleared response example**
```json theme={null}
{
"upi": "clean99@okaxis",
"status": "CLEARED",
"confidence": null,
"cluster_id": null,
"sources": [],
"evidence_count": 0
}
```
### Take action based on status and confidence
Map the response to a concrete action in your system:
| Status | Confidence | Recommended action |
| --------- | ---------- | --------------------------------------------------- |
| `CLEARED` | — | Allow the payment to proceed |
| `FLAGGED` | 0.85–1.0 | **Block** the payment; alert your fraud team |
| `FLAGGED` | 0.60–0.84 | Hold and route to **manual review** queue |
| `FLAGGED` | 0.0–0.59 | Allow with **enhanced monitoring**; flag for review |
The Python snippet below shows this logic as a reusable screening function:
```python theme={null}
import requests
def screen_upi(vpa: str, api_key: str) -> dict:
resp = requests.get(
"https://api.fraudtraceai.com/v1/verify/upi",
params={"upi": vpa},
headers={"Authorization": f"Bearer {api_key}"}
)
resp.raise_for_status()
return resp.json()
result = screen_upi("xxxxx@ybl", "YOUR_API_KEY")
if result["status"] == "FLAGGED" and result["confidence"] >= 0.85:
# Block the payment
raise ValueError(f"High-risk UPI blocked: cluster {result['cluster_id']}")
elif result["status"] == "FLAGGED":
# Queue for manual review
queue_for_review(result)
else:
# Proceed with payment
approve_payment()
```
Log the `cluster_id` and `confidence` score alongside your payment record at
the time of screening. This creates an immutable audit trail that is valuable
for regulatory reporting, chargeback disputes, and internal fraud
investigations.
## Confidence thresholds reference
| Range | Risk level | Suggested action |
| --------- | ------------- | ----------------------------- |
| 0.85–1.0 | High | Block or escalate immediately |
| 0.60–0.84 | Medium | Route to manual review |
| 0.0–0.59 | Low | Monitor; allow with caution |
| `CLEARED` | None detected | Allow |
## What happens next
Once you have a `cluster_id` from a flagged result, you can retrieve full cluster details — including all associated VPAs and evidence — using the cluster lookup endpoint:
```bash theme={null}
GET https://api.fraudtraceai.com/v1/verify/upi/cluster/{cluster_id}
```
This is useful when your fraud team wants to investigate the broader network a flagged VPA belongs to. See [Interpreting Results](/guides/interpreting-results) for a full breakdown of every response field.