Skip to main content
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