Order Verification API

AI-powered fraud detection for e-commerce orders.

Overview

The Order Verification API analyzes order data to detect potential fraud. It examines customer information, addresses, payment details, order patterns, and technical signals to provide a risk assessment with actionable recommendations.

Verify Order

Analyze an order for fraud risk.

Endpoint: POST /api/{organization}/order-verification

Request Body

Order Information

Customer Information

Customer History (Optional)

Company Information (Optional)

Addresses

Address Object:

Payment Information (Optional)

Technical Data (Optional)

Order Items (Optional)

Example Request

curl -X POST https://verify-ai.tdcapps.com/api/your-org/order-verification \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-12345",
    "orderAmount": 299.99,
    "currency": "USD",
    "orderTimestamp": "2024-01-15T14:30:00Z",
    "items": [
      {
        "name": "Wireless Headphones",
        "quantity": 1,
        "price": 299.99,
        "sku": "WH-1000"
      }
    ],
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com",
    "customerPhone": "+1234567890",
    "isFirstTimeCustomer": false,
    "accountAgeInDays": 180,
    "totalOrders": 3,
    "fulfilledOrders": 2,
    "averageOrderValue": 150.00,
    "shippingAddress": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "United States"
    },
    "billingAddress": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "United States"
    },
    "paymentInfo": {
      "brand": "Visa",
      "lastFourDigits": "4242",
      "expiry": "12/26",
      "holderName": "John Doe"
    },
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
  }'

Response

{
  "success": true,
  "data": {
    "riskScore": 25,
    "riskLevel": "low",
    "riskFactors": [
      {
        "factor": "IP Location Mismatch",
        "severity": "low",
        "description": "IP address location differs from shipping address, but within same country.",
        "category": "technical"
      }
    ],
    "reasoning": "This order shows low fraud risk. The customer has an established account history with 3 previous orders, and both billing and shipping addresses match. The email domain is legitimate and not associated with fraud databases.",
    "recommendations": [
      "Process order normally",
      "No additional verification required"
    ]
  }
}

Response Fields

Risk Score

Risk Factors

Each risk factor includes:

Risk Categories

Integration Examples

E-commerce Checkout

async function verifyOrderAtCheckout(orderData) {
  const response = await fetch(
    'https://verify-ai.tdcapps.com/api/your-org/order-verification',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    }
  )

  const result = await response.json()

  if (!result.success) {
    throw new Error(result.message)
  }

  const { riskScore, riskLevel, recommendations } = result.data

  // Handle based on risk level
  if (riskLevel === 'critical') {
    return { action: 'reject', reason: 'High fraud risk detected' }
  }

  if (riskLevel === 'high') {
    return { action: 'review', reason: 'Manual review required' }
  }

  return { action: 'approve' }
}

Order Event Integration

Use with your e-commerce platform's order-created event handler:

app.post('/orders/new', async (req, res) => {
  const order = req.body

  // Transform order data to API format
  const verificationData = {
    orderId: order.id,
    orderAmount: order.total,
    currency: order.currency,
    customerName: order.customer.name,
    customerEmail: order.customer.email,
    isFirstTimeCustomer: order.customer.ordersCount === 0,
    shippingAddress: order.shippingAddress,
    billingAddress: order.billingAddress,
    paymentInfo: {
      brand: order.payment.brand,
      lastFourDigits: order.payment.last4,
      expiry: order.payment.expiry,
      holderName: order.payment.holderName
    }
  }

  const result = await verifyOrder(verificationData)

  // Take action based on result
  if (result.data.riskLevel === 'critical') {
    await cancelOrder(order.id)
  }

  res.status(200).send('OK')
})

Best Practices

1. Provide Complete Data: More data leads to more accurate assessments
2. Include Customer History: Order history significantly improves accuracy
3. Handle All Risk Levels: Implement workflows for each risk tier
4. Log Results: Store verification results for dispute resolution
5. Set Thresholds: Define your acceptable risk levels based on business needs

Error Responses

400 Bad Request

Invalid request parameters:

{
  "success": false,
  "message": "Invalid request body: ..."
}

402 Payment Required

Insufficient credits:

{
  "success": false,
  "message": "Insufficient credits. Please purchase credits to continue."
}