> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txncheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UPI by Mobile

> Get UPI VPAs linked to a mobile number

# UPI by Mobile

Retrieve and validate all UPI IDs (VPAs) linked to a mobile number without OTP verification.

## Overview

This endpoint helps businesses:

* Verify if a UPI handle is active
* Check if the handle is linked to the correct user
* Retrieve all VPAs associated with a mobile number
* Prevent fraud by validating payment addresses

## Request

<ParamField body="mobile" type="string" required>
  Mobile number in Indian international format (`+91XXXXXXXXXX`)
</ParamField>

<ParamField body="name" type="string" required>
  Name of the mobile number owner (e.g., `Rajesh Kumar`)
</ParamField>

<ParamField body="async" type="boolean" default="true">
  If `true` (default), request is queued and result delivered via webhook. If `false`, wait for result synchronously (up to 30 seconds).
</ParamField>

### Headers

| Header         | Value              | Required |
| -------------- | ------------------ | -------- |
| `X-API-Key`    | Your API key       | Yes      |
| `Content-Type` | `application/json` | Yes      |

### Example Request (Async Mode - Default)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
    -H "X-API-Key: fb_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "mobile": "+919876543210",
      "name": "Rajesh Kumar"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.txncheck.in/api/v1/upi-by-mobile",
      headers={
          "X-API-Key": "fb_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={"mobile": "+919876543210", "name": "Rajesh Kumar"}
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.txncheck.in/api/v1/upi-by-mobile',
    { mobile: '+919876543210', name: 'Rajesh Kumar' },
    {
      headers: {
        'X-API-Key': 'fb_your_api_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log(response.data);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.txncheck.in/api/v1/upi-by-mobile");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "X-API-Key: fb_your_api_key_here",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      "mobile" => "+919876543210",
      "name" => "Rajesh Kumar"
  ]));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  payload := map[string]string{"mobile": "+919876543210", "name": "Rajesh Kumar"}
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST", "https://api.txncheck.in/api/v1/upi-by-mobile", bytes.NewBuffer(body))
  req.Header.Set("X-API-Key", "fb_your_api_key_here")
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, _ := client.Do(req)
  ```
</CodeGroup>

### Example Request (Sync Mode)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
    -H "X-API-Key: fb_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "mobile": "+919876543210",
      "name": "Rajesh Kumar",
      "async": false
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.txncheck.in/api/v1/upi-by-mobile",
      headers={
          "X-API-Key": "fb_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={"mobile": "+919876543210", "name": "Rajesh Kumar", "async": False}
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.txncheck.in/api/v1/upi-by-mobile',
    { mobile: '+919876543210', name: 'Rajesh Kumar', async: false },
    {
      headers: {
        'X-API-Key': 'fb_your_api_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log(response.data);
  ```
</CodeGroup>

## Response

<Tabs>
  <Tab title="Async Mode (202)">
    ### 202 Accepted

    Request accepted and queued for processing. Results will be delivered via webhook.

    ```json theme={null}
    {
      "statusCode": 202,
      "message": "Request accepted and queued for processing",
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "QUEUED"
    }
    ```

    ### Result Data (via webhook or polling)

    When the request completes, you'll receive a webhook or can poll the status endpoint:

    ```json theme={null}
    {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "method": "upi-by-mobile",
      "status": "COMPLETED",
      "result": {
        "upiByMobile": {
          "name": "JOHN DOE",
          "vpas": [
            "johndoe@upi",
            "9876543210@paytm",
            "9876543210@ybl"
          ],
          "status": "1"
        }
      },
      "webhookStatus": "SENT",
      "createdAt": "2025-01-11T10:30:00.000Z",
      "completedAt": "2025-01-11T10:30:05.000Z"
    }
    ```
  </Tab>

  <Tab title="Sync Mode (200)">
    ### 200 OK

    Request completed synchronously. Result is returned in the response body.

    ```json theme={null}
    {
      "statusCode": 200,
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "method": "upi-by-mobile",
      "status": "COMPLETED",
      "result": {
        "upiByMobile": {
          "name": "JOHN DOE",
          "vpas": [
            "johndoe@upi",
            "9876543210@paytm",
            "9876543210@ybl"
          ],
          "status": "1"
        }
      },
      "createdAt": "2025-01-11T10:30:00.000Z",
      "completedAt": "2025-01-11T10:30:05.000Z"
    }
    ```

    <Warning>
      Sync mode has a 30-second timeout. If processing takes longer, you'll receive a 408 Request Timeout error. Use async mode for potentially slow requests.
    </Warning>
  </Tab>
</Tabs>

### Result Fields

| Field    | Type      | Description                                   |
| -------- | --------- | --------------------------------------------- |
| `name`   | string    | Name associated with the mobile number        |
| `upi`    | string\[] | Array of UPI VPAs linked to the mobile number |
| `status` | string    | `"1"` if data found, `"0"` if not found       |

## Error Responses

### 400 Bad Request

Invalid mobile number format.

```json theme={null}
{
  "statusCode": 400,
  "message": ["Mobile must be in format +91XXXXXXXXXX (Indian number)"],
  "error": "Bad Request"
}
```

### 401 Unauthorized

Invalid or missing API key.

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
```

### 402 Payment Required

Insufficient account balance.

```json theme={null}
{
  "statusCode": 402,
  "message": "Insufficient wallet balance",
  "error": "Payment Required"
}
```

### 403 Forbidden

Method not enabled for your account.

```json theme={null}
{
  "statusCode": 403,
  "message": "Access to method 'upi-by-mobile' is not allowed",
  "error": "Forbidden"
}
```

### 408 Request Timeout (Sync Mode Only)

Request processing timed out. Only occurs with `async: false`.

```json theme={null}
{
  "statusCode": 408,
  "message": "Request processing timed out after 30 seconds. Use async mode or check status later with request ID: 550e8400-e29b-41d4-a716-446655440000",
  "error": "Request Timeout"
}
```

### 429 Too Many Requests

Rate limit exceeded.

```json theme={null}
{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}
```

## Use Cases

<AccordionGroup>
  <Accordion title="Customer Onboarding">
    Verify customer identity by checking their UPI addresses during account creation.
  </Accordion>

  <Accordion title="Payment Validation">
    Confirm that a provided UPI address belongs to the expected customer before processing payments.
  </Accordion>

  <Accordion title="Fraud Prevention">
    Cross-reference UPI addresses with customer information to detect potential fraud.
  </Accordion>
</AccordionGroup>