Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.humancheck.dev/llms.txt

Use this file to discover all available pages before exploring further.

This is an example implementation of a payment approval workflow using Humancheck. This demonstrates how to integrate human review for high-value transactions, but Humancheck can be adapted to any payment or financial approval scenario.

​
Overview

The payment approval workflow:
  1. Agent processes payment request
  2. If amount exceeds threshold, request human review
  3. Reviewer approves, rejects, or modifies the payment
  4. Agent processes the payment based on decision

​
Implementation

​
Basic Payment Workflow

import httpx
import asyncio

async def payment_workflow(amount, vendor, account_number):
    """Process payment with human review for high-value transactions."""
    async with httpx.AsyncClient() as client:
        # Threshold for auto-approval
        AUTO_APPROVAL_THRESHOLD = 1000
        
        if amount > AUTO_APPROVAL_THRESHOLD:
            # Request human review
            response = await client.post(
                "https://api.humancheck.dev/reviews",
                headers={
                    "Authorization": "Bearer your-api-key-here",
                    "Content-Type": "application/json"
                },
                json={
                    "task_type": "payment",
                    "proposed_action": f"Process payment of ${amount:,.2f} to {vendor} (Account: {account_number})",
                    "agent_reasoning": f"Payment amount (${amount:,.2f}) exceeds auto-approval threshold of ${AUTO_APPROVAL_THRESHOLD:,.2f}",
                    "confidence_score": 0.9,
                    "urgency": "high" if amount > 5000 else "medium",
                    "metadata": {
                        "amount": amount,
                        "vendor": vendor,
                        "account_number": account_number,
                        "currency": "USD"
                    },
                    "blocking": True  # Wait for decision
                }
            )
            review = response.json()
            
            # Get decision
            decision = review.get("decision")
            if not decision:
                # Poll for decision
                decision_response = await client.get(
                    f"https://api.humancheck.dev/reviews/{review['id']}/decision",
                    headers={"Authorization": "Bearer your-api-key-here"}
                )
                decision = decision_response.json()
            
            # Process based on decision
            if decision["decision_type"] == "approve":
                # Process payment
                result = await process_payment(amount, vendor, account_number)
                return {"status": "completed", "transaction_id": result["id"]}
            elif decision["decision_type"] == "modify":
                # Extract modified amount from modified_action
                modified_action = decision["modified_action"]
                # Parse modified amount (simplified)
                modified_amount = extract_amount(modified_action)
                result = await process_payment(modified_amount, vendor, account_number)
                return {"status": "completed", "transaction_id": result["id"], "modified": True}
            else:
                return {"status": "rejected", "reason": decision.get("notes")}
        else:
            # Auto-approve small payments
            result = await process_payment(amount, vendor, account_number)
            return {"status": "completed", "transaction_id": result["id"], "auto_approved": True}

# Helper function to extract amount from modified action
def extract_amount(action_string):
    """Extract amount from action string."""
    import re
    match = re.search(r'\$?([\d,]+\.?\d*)', action_string)
    if match:
        return float(match.group(1).replace(',', ''))
    return None

# Usage
asyncio.run(payment_workflow(5000, "ACME Corp", "1234567890"))

​
Advanced Features

​
Multi-Currency Support

async def payment_workflow_multicurrency(amount, currency, vendor):
    """Process payment with multi-currency support."""
    # Convert to USD for threshold checking
    usd_amount = convert_to_usd(amount, currency)
    
    response = await client.post(
        "https://api.humancheck.dev/reviews",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
            "task_type": "payment",
            "proposed_action": f"Process payment of {amount} {currency} ({usd_amount} USD) to {vendor}",
            "metadata": {
                "amount": amount,
                "currency": currency,
                "usd_equivalent": usd_amount,
                "vendor": vendor
            },
            "urgency": "high" if usd_amount > 5000 else "medium"
        }
    )

​
Batch Payments

async def batch_payment_workflow(payments):
    """Process multiple payments with review."""
    total_amount = sum(p["amount"] for p in payments)
    
    if total_amount > 10000:
        # Review required for large batch
        response = await client.post(
        "https://api.humancheck.dev/reviews",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
                "task_type": "payment",
                "proposed_action": f"Process batch payment of {len(payments)} payments totaling ${total_amount:,.2f}",
                "agent_reasoning": f"Batch payment exceeds threshold",
                "metadata": {
                    "payment_count": len(payments),
                    "total_amount": total_amount,
                    "payments": payments
                },
                "blocking": True
            }
        )
        review = response.json()
        decision = review.get("decision")
        
        if decision["decision_type"] == "approve":
            # Process all payments
            results = []
            for payment in payments:
                result = await process_payment(**payment)
                results.append(result)
            return results

​
Payment Scheduling

async def scheduled_payment_workflow(amount, vendor, scheduled_date):
    """Schedule payment with review."""
    response = await client.post(
        "https://api.humancheck.dev/reviews",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
            "task_type": "payment",
            "proposed_action": f"Schedule payment of ${amount:,.2f} to {vendor} for {scheduled_date}",
            "agent_reasoning": f"Scheduled payment for future date",
            "metadata": {
                "amount": amount,
                "vendor": vendor,
                "scheduled_date": scheduled_date.isoformat(),
                "is_scheduled": True
            },
            "urgency": "low"  # Lower urgency for scheduled payments
        }
    )

​
Routing Rules

Route high-value payments to specific reviewers: 
# Create routing rule via API
await client.post(
        "https://api.humancheck.dev/reviews",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
        "name": "High-value payments to finance team",
        "organization_id": 1,
        "priority": 100,
        "conditions": {
            "task_type": {"operator": "=", "value": "payment"},
            "metadata.amount": {"operator": ">", "value": 10000}
        },
        "assign_to_team_id": 5,  # Finance team
        "is_active": True
    }
)

​
Dashboard Integration

The payment appears in the dashboard with:
  • Payment amount and currency
  • Vendor information
  • Account details
  • Review history
  • Approval/rejection/modification options
Reviewers can:
  • ✅ Approve the payment as-is
  • ❌ Reject with reason
  • ✏️ Modify the amount or details before approving

​
Best Practices

  1. Set appropriate thresholds: Use different thresholds for different payment types
  2. Include all relevant details: Vendor, account number, purpose, etc.
  3. Use urgency levels: High urgency for time-sensitive payments
  4. Provide context: Include why the review is needed
  5. Track modifications: Log when payments are modified before approval

​
Next Steps