Iconus Tech/Documentation

Checks API

Complete reference for managing checks with the Iconus Tech Check Fraud Prevention API.

Overview

The Checks API allows you to register, verify, and manage checks. All endpoints require API key authentication.

Base URL: https://api.iconustech.com/v1
Authentication: API Key (x-api-key header)

Endpoints

Register a Check

Create a new check record with hash-based verification.

Endpoint: POST /v1/checks/register

Register Check
curl -X POST https://api.iconustech.com/v1/checks/register \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "checkNumber": "1001",
  "amount": 1500.00,
  "payeeName": "Acme Corporation",
  "dateIssued": "2025-11-12",
  "memo": "Invoice #12345"
}'

Request Body:

| Field | Type | Required | Description | |-------|------|----------|-------------| | checkNumber | string | Yes | Unique check number | | amount | number | Yes | Check amount in USD | | payeeName | string | Yes | Payee name | | dateIssued | string | Yes | Date in YYYY-MM-DD format | | memo | string | No | Optional memo/note |

Response (201 Created):

json
{
"success": true,
"data": {
  "checkId": "check_abc123def456",
  "qrToken": "qr_xyz789abc123",
  "checkHash": "sha256:a1b2c3d4e5f6...",
  "fraudScore": 0,
  "riskLevel": "LOW",
  "status": "ACTIVE",
  "createdAt": "2025-11-12T10:30:00Z"
}
}

JavaScript Example:

register-check.js
async function registerCheck(checkData) {
const response = await fetch('https://api.iconustech.com/v1/checks/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ICONUS_API_KEY,
  },
  body: JSON.stringify(checkData),
});
 
const result = await response.json();
 
if (result.success) {
  console.log('Check registered:', result.data.checkId);
  console.log('QR Token:', result.data.qrToken);
  return result.data;
}
 
throw new Error(result.message);
}
 
// Usage
const check = await registerCheck({
checkNumber: '1001',
amount: 1500.00,
payeeName: 'Acme Corporation',
dateIssued: '2025-11-12',
memo: 'Invoice #12345',
});

Python Example:

register_check.py
import requests
import os
 
def register_check(check_data):
  response = requests.post(
      'https://api.iconustech.com/v1/checks/register',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': os.getenv('ICONUS_API_KEY'),
      },
      json=check_data
  )
  
  result = response.json()
  
  if result['success']:
      print(f"Check registered: {result['data']['checkId']}")
      print(f"QR Token: {result['data']['qrToken']}")
      return result['data']
  
  raise Exception(result['message'])
 
# Usage
check = register_check({
  'checkNumber': '1001',
  'amount': 1500.00,
  'payeeName': 'Acme Corporation',
  'dateIssued': '2025-11-12',
  'memo': 'Invoice #12345',
})

Verify a Check

Verify a check using its QR token to detect fraud.

Endpoint: POST /v1/checks/verify

Verify Check
curl -X POST https://api.iconustech.com/v1/checks/verify \
-H "Content-Type: application/json" \
-d '{"qrToken": "qr_xyz789abc123"}'

Request Body:

| Field | Type | Required | Description | |-------|------|----------|-------------| | qrToken | string | Yes | QR token from check |

Response (200 OK) - Authentic:

json
{
"success": true,
"data": {
  "checkId": "check_abc123def456",
  "checkNumber": "1001",
  "amount": 1500.00,
  "payeeName": "Acme Corporation",
  "fraudDetected": false,
  "fraudScore": 5,
  "riskLevel": "LOW",
  "status": "ACTIVE",
  "verificationCount": 1,
  "lastVerified": "2025-11-12T14:30:00Z"
}
}

Response (200 OK) - Fraudulent:

json
{
"success": false,
"fraudDetected": true,
"fraudScore": 85,
"riskLevel": "HIGH",
"reasons": [
  "Check has been voided",
  "Multiple verification attempts detected",
  "Amount exceeds normal patterns"
]
}

JavaScript Example:

verify-check.js
async function verifyCheck(qrToken) {
const response = await fetch('https://api.iconustech.com/v1/checks/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ qrToken }),
});
 
const result = await response.json();
 
if (result.success && result.data.riskLevel === 'LOW') {
  console.log('✅ Check is AUTHENTIC');
  return { authentic: true, check: result.data };
} else if (result.fraudDetected) {
  console.log('❌ FRAUD DETECTED');
  console.log('Reasons:', result.reasons);
  return { authentic: false, reasons: result.reasons };
}
 
return result;
}
 
// Usage
const verification = await verifyCheck('qr_xyz789abc123');

Get Check by ID

Retrieve full check details including verification history.

Endpoint: GET /v1/checks/:checkId

Get Check
curl https://api.iconustech.com/v1/checks/check_abc123def456 \
-H "x-api-key: YOUR_API_KEY"

Response (200 OK):

json
{
"success": true,
"data": {
  "checkId": "check_abc123def456",
  "checkNumber": "1001",
  "amount": 1500.00,
  "payeeName": "Acme Corporation",
  "dateIssued": "2025-11-12",
  "memo": "Invoice #12345",
  "qrToken": "qr_xyz789abc123",
  "checkHash": "sha256:a1b2c3d4...",
  "fraudScore": 5,
  "riskLevel": "LOW",
  "status": "ACTIVE",
  "verificationCount": 3,
  "createdAt": "2025-11-12T10:30:00Z",
  "updatedAt": "2025-11-12T14:22:00Z"
}
}

JavaScript Example:

get-check.js
async function getCheck(checkId) {
const response = await fetch(
  `https://api.iconustech.com/v1/checks/${checkId}`,
  {
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
const result = await response.json();
return result.data;
}
 
// Usage
const check = await getCheck('check_abc123def456');
console.log('Check:', check);

List Your Checks

Get a paginated list of all checks registered by your API key.

Endpoint: GET /v1/checks

List Checks
curl "https://api.iconustech.com/v1/checks?limit=50&offset=0" \
-H "x-api-key: YOUR_API_KEY"

Query Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | integer | 50 | Number of results (max: 100) | | offset | integer | 0 | Pagination offset | | status | string | - | Filter by status (ACTIVE, VOIDED, EXPIRED) | | riskLevel | string | - | Filter by risk (LOW, MEDIUM, HIGH) |

Response (200 OK):

json
{
"success": true,
"data": {
  "checks": [
    {
      "checkId": "check_abc123",
      "checkNumber": "1001",
      "amount": 1500.00,
      "payeeName": "Acme Corp",
      "fraudScore": 5,
      "riskLevel": "LOW",
      "status": "ACTIVE",
      "createdAt": "2025-11-12T10:30:00Z"
    },
    {
      "checkId": "check_def456",
      "checkNumber": "1002",
      "amount": 2500.00,
      "payeeName": "Tech Inc",
      "fraudScore": 0,
      "riskLevel": "LOW",
      "status": "ACTIVE",
      "createdAt": "2025-11-11T15:20:00Z"
    }
  ],
  "pagination": {
    "total": 127,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
}

JavaScript Example:

list-checks.js
async function listChecks(options = {}) {
const { limit = 50, offset = 0, status, riskLevel } = options;
 
const params = new URLSearchParams({
  limit: limit.toString(),
  offset: offset.toString(),
});
 
if (status) params.append('status', status);
if (riskLevel) params.append('riskLevel', riskLevel);
 
const response = await fetch(
  `https://api.iconustech.com/v1/checks?${params}`,
  {
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
const result = await response.json();
return result.data;
}
 
// Usage
const { checks, pagination } = await listChecks({
limit: 50,
status: 'ACTIVE',
riskLevel: 'LOW',
});
 
console.log(`Found ${checks.length} checks`);
console.log(`Total: ${pagination.total}`);

Check Status

Checks can have the following statuses:

| Status | Description | |--------|-------------| | ACTIVE | Check is valid and can be verified | | VOIDED | Check has been voided by issuer | | EXPIRED | Check has expired (>180 days old) | | CASHED | Check has been successfully cashed |

Risk Levels

Fraud detection assigns risk levels based on AI analysis:

| Risk Level | Score Range | Action | |------------|-------------|--------| | LOW | 0-20 | ✅ Safe to accept | | MEDIUM | 21-60 | ⚠️ Requires review | | HIGH | 61-85 | ❌ Recommend rejection | | CRITICAL | 86-100 | 🚫 Automatic rejection |

Error Responses

400 Bad Request

json
{
"error": "Bad Request",
"message": "Missing required field: checkNumber",
"statusCode": 400
}

401 Unauthorized

json
{
"error": "Unauthorized",
"message": "Invalid or missing API key",
"statusCode": 401
}

404 Not Found

json
{
"error": "Not Found",
"message": "Check not found",
"statusCode": 404
}

429 Rate Limit Exceeded

json
{
"error": "Rate Limit Exceeded",
"message": "Rate limit exceeded",
"usage": {
  "current": 1000,
  "limit": 1000,
  "tier": "FREE"
},
"upgradeUrl": "https://iconustech.com/pricing",
"statusCode": 429
}

Best Practices

1. Store QR Tokens Securely

store-qr-token.js
// Store QR token with check record
const check = await registerCheck(checkData);
 
// Save to database
await db.checks.create({
checkId: check.checkId,
qrToken: check.qrToken,
checkNumber: checkData.checkNumber,
amount: checkData.amount,
// ... other fields
});
 
// Print QR code on physical check
await printQRCode(check.qrToken);

2. Handle Verification Results

handle-verification.js
async function handleCheckVerification(qrToken) {
const result = await verifyCheck(qrToken);
 
if (result.authentic && result.check.riskLevel === 'LOW') {
  // Accept check
  await processPayment(result.check);
  return { action: 'ACCEPT', check: result.check };
}
 
if (result.check?.riskLevel === 'MEDIUM') {
  // Flag for manual review
  await flagForReview(result.check);
  return { action: 'REVIEW', check: result.check };
}
 
// Reject check
await rejectCheck(result.reasons);
return { action: 'REJECT', reasons: result.reasons };
}

3. Implement Pagination

paginate-checks.js
async function getAllChecks() {
const allChecks = [];
let offset = 0;
const limit = 100;
 
while (true) {
  const { checks, pagination } = await listChecks({ limit, offset });
  allChecks.push(...checks);
  
  if (!pagination.hasMore) break;
  offset += limit;
}
 
return allChecks;
}

Next Steps

Support