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

# Testing Guide

> Test your integration before going live

# Testing Guide

This guide covers how to test your TxnCheck API integration effectively before deploying to production.

## Test Environment

<Info>
  TxnCheck provides a test environment for development and testing. Contact your account manager to obtain test API credentials.
</Info>

### Test vs Production

| Aspect       | Test                     | Production             |
| ------------ | ------------------------ | ---------------------- |
| API Endpoint | Same (`api.txncheck.in`) | Same                   |
| API Keys     | Test keys provided       | Production keys        |
| Data         | Simulated responses      | Real verification data |
| Billing      | No charges               | Per-request billing    |
| Webhooks     | Delivered normally       | Delivered normally     |

## Integration Checklist

Before going live, verify your integration handles these scenarios:

<AccordionGroup>
  <Accordion title="API Authentication">
    * [ ] API key is stored securely (environment variables)
    * [ ] Requests include `X-API-Key` header
    * [ ] Request signing works (if enabled)
    * [ ] Handle `401 Unauthorized` errors gracefully
  </Accordion>

  <Accordion title="Request Submission">
    * [ ] Submit UPI by Mobile requests successfully
    * [ ] Submit KYC by Mobile requests successfully
    * [ ] Submit VPA Chargeback Check requests successfully
    * [ ] Submit Full Check requests successfully
    * [ ] Handle validation errors (400 Bad Request)
    * [ ] Store request IDs for tracking
  </Accordion>

  <Accordion title="Result Retrieval">
    * [ ] Poll request status correctly
    * [ ] Handle all status types (QUEUED, PROCESSING, COMPLETED, FAILED, PARTIAL)
    * [ ] Parse result data correctly
    * [ ] Handle error responses
  </Accordion>

  <Accordion title="Webhooks">
    * [ ] Webhook endpoint is HTTPS and publicly accessible
    * [ ] Verify webhook signatures
    * [ ] Handle `request.completed` events
    * [ ] Handle `request.failed` events
    * [ ] Handle `request.partial` events
    * [ ] Process events idempotently (handle duplicates)
    * [ ] Return 2xx response quickly
  </Accordion>

  <Accordion title="Error Handling">
    * [ ] Handle network timeouts gracefully
    * [ ] Implement retry logic with backoff
    * [ ] Handle rate limit errors (429)
    * [ ] Handle insufficient balance errors (402)
    * [ ] Log errors for debugging
  </Accordion>
</AccordionGroup>

## Testing Request Flow

### 1. Submit a Verification Request

```bash theme={null}
curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
```

Expected response:

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

### 2. Poll for Results

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

Expected response (processing):

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "PROCESSING",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}
```

Expected response (completed):

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

### 3. Verify Webhook Receipt

Check that your webhook endpoint received the notification:

```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"],
      "status": "1"
    },
    "completedAt": "2025-01-11T10:30:05.000Z"
  }
}
```

## Testing Error Scenarios

### Invalid Mobile Number

```bash theme={null}
curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "invalid"}'
```

Expected error:

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

### Invalid API Key

```bash theme={null}
curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: invalid_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
```

Expected error:

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

### Method Not Allowed

```bash theme={null}
curl -X POST "https://api.txncheck.in/api/v1/full-check" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
```

Expected error (if method not enabled):

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

## Testing Webhooks Locally

### Using ngrok

1. Install ngrok: `npm install -g ngrok`
2. Start your local server on port 3000
3. Create a tunnel: `ngrok http 3000`
4. Use the ngrok URL as your webhook endpoint

```bash theme={null}
ngrok http 3000
# Output: https://abc123.ngrok.io -> http://localhost:3000
```

### Using Webhook.site

For quick testing, use [webhook.site](https://webhook.site):

1. Visit webhook.site and copy your unique URL
2. Configure this URL as your webhook endpoint (contact support)
3. Submit a verification request
4. View the webhook payload on webhook.site

## Polling Best Practices

When polling for results, implement exponential backoff:

```javascript theme={null}
async function pollForResult(requestId, maxAttempts = 10) {
  let attempt = 0;
  let delay = 1000; // Start with 1 second

  while (attempt < maxAttempts) {
    const response = await fetch(
      `https://api.txncheck.in/api/v1/requests/${requestId}`,
      { headers: { 'X-API-Key': API_KEY } }
    );
    
    const data = await response.json();
    
    if (data.status === 'COMPLETED' || data.status === 'FAILED' || data.status === 'PARTIAL') {
      return data;
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, delay));
    
    // Increase delay (max 30 seconds)
    delay = Math.min(delay * 1.5, 30000);
    attempt++;
  }
  
  throw new Error('Polling timeout');
}
```

## Going Live

<Steps>
  <Step title="Complete Testing">
    Ensure all checklist items pass in test mode
  </Step>

  <Step title="Request Production Keys">
    Contact your account manager to request production API credentials
  </Step>

  <Step title="Update Configuration">
    Replace test API key with production key in your production environment
  </Step>

  <Step title="Verify Webhook URL">
    Ensure your webhook endpoint points to your production server
  </Step>

  <Step title="Top Up Balance">
    Ensure your merchant account has sufficient balance for API calls
  </Step>

  <Step title="Monitor">
    Watch the dashboard for your first live verifications
  </Step>
</Steps>

<Warning>
  Never use production API keys in development or testing environments. Always keep test and production credentials separate.
</Warning>

## Common Testing Mistakes

<CardGroup cols={2}>
  <Card title="Hardcoding API Keys" icon="key">
    Always use environment variables for API credentials
  </Card>

  <Card title="Skipping Webhook Verification" icon="shield-xmark">
    Always verify signatures, even in test mode
  </Card>

  <Card title="Not Testing Errors" icon="bug">
    Test error scenarios, not just happy paths
  </Card>

  <Card title="Ignoring Timeouts" icon="clock">
    Implement proper timeout handling and retries
  </Card>
</CardGroup>

## Need Help?

<Card title="Developer Support" icon="headset" href="https://app.txncheck.com">
  Contact our support team if you have questions about testing
</Card>