Security Overview

This guide covers security best practices for integrating with the TxnCheck API, protecting your API keys, and handling sensitive data.

Security Architecture

Key Security Principles

Defense in Depth

Multiple layers of security controls to protect against various attack vectors

Least Privilege

Grant minimum necessary permissions for API keys and service accounts

Zero Trust

Verify every request, even from internal systems

Audit Everything

Log all API interactions for compliance and incident response

Authentication Security

API Key Protection

Your API key grants access to paid services and sensitive verification data. Treat it like a password.

Do:

Store API keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
Use environment variables, never hardcode keys
Rotate keys periodically (every 90 days recommended)
Use separate keys for development, staging, and production

Don’t:

Commit API keys to version control
Share keys via email or chat
Log API keys in application logs
Expose keys in client-side code

// ✅ Good: Load from environment
const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
});

// ❌ Bad: Hardcoded key
const client = new TxnCheckClient({
  apiKey: 'fb_live_abc123xyz',
});

Request Signing (Optional but Recommended)

Enable HMAC-SHA256 request signing for additional security:

const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
  secretKey: process.env.FRAUD_BUSTER_SECRET_KEY!, // For signing
});

Request signing provides:

Integrity: Ensures request wasn’t modified in transit
Replay Protection: Timestamp prevents replay attacks
Non-repudiation: Proves request originated from your system

Transport Security

HTTPS Requirements

All API communication must use HTTPS with TLS 1.2 or higher:

// The SDK enforces HTTPS by default
const client = new TxnCheckClient({
  apiKey: process.env.FRAUD_BUSTER_API_KEY!,
  baseUrl: 'https://api.txncheck.in/api/v1', // HTTPS required
});

Certificate Validation

Always validate SSL certificates:

// ✅ Good: Default behavior - validates certificates
const response = await fetch(url);

// ❌ Bad: Disabling certificate validation
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'; // Never do this!

Input Validation

Always validate input before sending to the API:

// Validate mobile number format
function validateMobile(mobile: string): boolean {
  return /^\+91\d{10}$/.test(mobile);
}

// Validate VPA format
function validateVPA(vpa: string): boolean {
  return /^[a-zA-Z0-9._-]+@[a-zA-Z0-9]+$/.test(vpa);
}

// Use validation before API calls
if (!validateMobile(userInput.mobile)) {
  throw new ValidationError('Invalid mobile number format');
}

const result = await client.upiByMobile(userInput.mobile, { sync: true });

Rate Limiting

Implement client-side rate limiting to avoid hitting API limits:

import Bottleneck from 'bottleneck';

const limiter = new Bottleneck({
  reservoir: 100, // Initial tokens
  reservoirRefreshAmount: 100, // Refill amount
  reservoirRefreshInterval: 60 * 1000, // Refill every minute
  maxConcurrent: 5, // Max concurrent requests
});

async function rateLimitedRequest(mobile: string) {
  return limiter.schedule(() => client.upiByMobile(mobile, { sync: true }));
}

Webhook Security

Signature Verification

Always verify webhook signatures to ensure authenticity:

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secretKey: string
): boolean {
  // Check timestamp to prevent replay attacks
  const webhookTime = parseInt(timestamp, 10);
  const currentTime = Date.now();
  const maxAge = 5 * 60 * 1000; // 5 minutes
  
  if (Math.abs(currentTime - webhookTime) > maxAge) {
    return false;
  }

  // Verify signature
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secretKey)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Webhook Endpoint Security

Secure your webhook endpoint:

app.post('/webhook/fraud-buster', 
  // Rate limit webhooks
  rateLimit({ windowMs: 60000, max: 100 }),
  
  // Verify signature middleware
  webhookSignatureMiddleware(process.env.WEBHOOK_SECRET!),
  
  // Process webhook
  async (req, res) => {
    // Handle webhook...
    res.json({ status: 'ok' });
  }
);

Error Handling Security

Don’t Expose Internal Errors

// ✅ Good: Generic error message to client
app.use((err, req, res, next) => {
  console.error('Internal error:', err); // Log full error
  res.status(500).json({
    error: 'An error occurred processing your request',
  });
});

// ❌ Bad: Exposing internal details
app.use((err, req, res, next) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack, // Never expose stack traces!
  });
});

Secure Logging

Log enough for debugging without exposing sensitive data:

// ✅ Good: Mask sensitive data in logs
function logAPICall(mobile: string, result: any) {
  console.log({
    action: 'verification',
    mobile: maskMobile(mobile), // +91****543210
    status: result.status,
    requestId: result.requestId,
    timestamp: new Date().toISOString(),
  });
}

function maskMobile(mobile: string): string {
  return mobile.slice(0, 3) + '****' + mobile.slice(-6);
}

// ❌ Bad: Logging full mobile numbers
console.log(`Verified mobile: ${mobile}`);

Security Checklist

Before going to production, verify:

API Key Security

API keys stored in secrets manager
No keys in source code or version control
Separate keys for dev/staging/production
Key rotation process documented

Transport Security

All API calls use HTTPS
Certificate validation enabled
No sensitive data in URLs (use POST body)

Input Validation

Mobile numbers validated before API calls
VPA formats validated
Input sanitization in place

Webhook Security

Signature verification implemented
Timestamp validation (replay protection)
Rate limiting on webhook endpoint
HTTPS-only webhook URL

Logging & Monitoring

Sensitive data masked in logs
API errors logged for debugging
Alerting on unusual patterns
Audit trail for compliance

Incident Response

If you suspect your API key has been compromised:

Immediately rotate the API key in your dashboard
Review recent API usage for unauthorized calls
Check your systems for the source of the leak
Update all deployed applications with new keys
Contact TxnCheck support if needed

API Keys

Detailed guide on managing API keys

Data Handling

Handling PII and sensitive data

Compliance

Regulatory compliance guidance

Authentication

API authentication details

Batch Screening API Key Management

​Security Overview

​Security Architecture

​Key Security Principles

Defense in Depth

Least Privilege

Zero Trust

Audit Everything

​Authentication Security

​API Key Protection

​Request Signing (Optional but Recommended)

​Transport Security

​HTTPS Requirements

​Certificate Validation

​Input Validation

​Rate Limiting

​Webhook Security

​Signature Verification

​Webhook Endpoint Security

​Error Handling Security

​Don’t Expose Internal Errors

​Secure Logging

​Security Checklist

​Incident Response

​Related Guides

API Keys

Data Handling

Compliance

Authentication

Security Overview

Security Architecture

Key Security Principles

Authentication Security

API Key Protection

Request Signing (Optional but Recommended)

Transport Security

HTTPS Requirements

Certificate Validation

Input Validation

Rate Limiting

Webhook Security

Signature Verification

Webhook Endpoint Security

Error Handling Security

Don’t Expose Internal Errors

Secure Logging

Security Checklist

Incident Response

Related Guides