> ## 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.

# Quick Start

> Make your first verification request in under 5 minutes

# Quick Start

This guide will help you make your first verification request using the TxnCheck API.

## Prerequisites

<Steps>
  <Step title="Obtain your API key">
    API keys are provided by the TxnCheck team during merchant onboarding. Contact your account manager or visit your [dashboard](https://app.txncheck.com) to request access.
  </Step>

  <Step title="Choose your execution mode">
    TxnCheck supports two modes:

    * **Async mode (default)**: Requests are queued, results delivered via webhooks or polling
    * **Sync mode**: Wait for results directly in the response (up to 30 seconds)
  </Step>
</Steps>

<Info>
  Merchant accounts and API keys are created by the TxnCheck team. Self-registration is not available.
</Info>

## Make Your First Request

Let's verify a mobile number to get associated UPI VPAs. You can choose between async and sync modes.

<Tabs>
  <Tab title="Async Mode (Default)">
    Async mode queues your request and delivers results via webhooks or polling.

    <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"
        }'
      ```

      ```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"}
      )
      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' },
        {
          headers: {
            'X-API-Key': 'fb_your_api_key_here',
            'Content-Type': 'application/json'
          }
        }
      );
      console.log(response.data);
      ```
    </CodeGroup>

    ### Response (202 Accepted)

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

  <Tab title="Sync Mode">
    Sync mode waits for the result and returns it directly in the response. Set `async: false` in your request.

    <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",
          "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", "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', async: false },
        {
          headers: {
            'X-API-Key': 'fb_your_api_key_here',
            'Content-Type': 'application/json'
          }
        }
      );
      console.log(response.data);
      ```
    </CodeGroup>

    ### Response (200 OK)

    ```json theme={null}
    {
      "statusCode": 200,
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "method": "upi-by-mobile",
      "status": "COMPLETED",
      "result": {
        "name": "JOHN DOE",
        "upi": ["johndoe@upi", "9876543210@paytm"],
        "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.
    </Warning>
  </Tab>
</Tabs>

## Get Results (Async Mode Only)

If you used async mode, results are delivered via webhooks (recommended) or by polling the status endpoint.

### Option 1: Webhooks (Recommended)

If you have a webhook configured, you'll receive the results automatically:

```json theme={null}
{
  "event": "request.completed",
  "timestamp": "2025-01-11T10:30:05.000Z",
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "method": "upi-by-mobile",
    "status": "COMPLETED",
    "result": {
      "name": "JOHN DOE",
      "upi": [
        "johndoe@upi",
        "9876543210@paytm",
        "9876543210@ybl"
      ],
      "status": "1"
    },
    "completedAt": "2025-01-11T10:30:05.000Z"
  }
}
```

### Option 2: Polling

Poll the request status endpoint until the status is `COMPLETED`, `FAILED`, or `PARTIAL`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.txncheck.in/api/v1/requests/550e8400-e29b-41d4-a716-446655440000" \
    -H "X-API-Key: fb_your_api_key_here"
  ```

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

  request_id = "550e8400-e29b-41d4-a716-446655440000"
  headers = {"X-API-Key": "fb_your_api_key_here"}

  while True:
      response = requests.get(
          f"https://api.txncheck.in/api/v1/requests/{request_id}",
          headers=headers
      )
      data = response.json()
      
      if data["status"] in ["COMPLETED", "FAILED", "PARTIAL"]:
          print(data)
          break
      
      time.sleep(2)  # Wait 2 seconds before next poll
  ```

  ```javascript Node.js theme={null}
  async function pollForResult(requestId) {
    const headers = { 'X-API-Key': 'fb_your_api_key_here' };
    
    while (true) {
      const response = await axios.get(
        `https://api.txncheck.in/api/v1/requests/${requestId}`,
        { headers }
      );
      
      if (['COMPLETED', 'FAILED', 'PARTIAL'].includes(response.data.status)) {
        return response.data;
      }
      
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }

  const result = await pollForResult('550e8400-e29b-41d4-a716-446655440000');
  console.log(result);
  ```
</CodeGroup>

### Completed Response

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

## Understanding the Response

| Field           | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `requestId`     | Unique identifier for tracking the request                               |
| `status`        | Current status: `QUEUED`, `PROCESSING`, `COMPLETED`, `FAILED`, `PARTIAL` |
| `result`        | Verification result data (when completed)                                |
| `result.name`   | Name associated with the mobile number                                   |
| `result.upi`    | Array of UPI VPAs linked to the mobile number                            |
| `result.status` | `"1"` indicates data was found                                           |

## What's Next?

<CardGroup cols={2}>
  <Card title="Set up Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time notifications when verifications complete
  </Card>

  <Card title="Explore All Methods" icon="code" href="/api-reference/overview">
    Learn about KYC verification, VPA checks, and more
  </Card>

  <Card title="Test Your Integration" icon="flask" href="/guides/testing">
    Use test mode to validate your implementation
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/errors/error-codes">
    Learn how to handle API errors
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Make sure you're including the `X-API-Key` header with a valid API key.
  </Accordion>

  <Accordion title="400 Bad Request - Invalid mobile format">
    Mobile numbers must be in Indian international format: `+91` followed by 10 digits.

    **Correct:** `+919876543210`

    **Incorrect:** `9876543210`, `+1-987-654-3210`
  </Accordion>

  <Accordion title="403 Forbidden - Method not allowed">
    Your API key may not have access to this verification method. Contact your account manager to enable it.
  </Accordion>

  <Accordion title="402 Payment Required">
    Your account balance is insufficient. Top up your balance in the merchant dashboard.
  </Accordion>
</AccordionGroup>