Payment Settlement Guide

Understand how payments are processed and settled with AI-powered processor selection.

Overview

The Huntrecht Platform provides automated daily settlement with:

• AI Processor Selection — Contextual Multi-Armed Bandit optimization
• Multi-Processor Support — Circle, Shopify Payments, Payoneer
• Dual Custody — TerraPay and Escrow.com for high-value transactions
• Cross-Chain USDC — Circle CCTP V2 for instant settlement

Settlement Flow

sequenceDiagram
    participant C as Customer
    participant H as Huntrecht
    participant AI as AI Processor Selector
    participant P as Processor
    participant S as Settlement
    
    C->>H: Submit Payment
    H->>AI: Select Optimal Processor
    AI-->>H: Selected Processor
    H->>P: Process Payment
    P-->>H: Payment Confirmation
    H->>S: Record Settlement
    S-->>C: Confirm Completion

AI Processor Selection

The system uses a Contextual Multi-Armed Bandit (CMAB) algorithm to select the best processor:

Decision Factors

Factor	Impact	Description
Amount	High	Transaction size
Customer History	Medium	Previous success rate
Region	Medium	Geographic location
Time of Day	Low	Peak vs off-peak
Processor Performance	High	Recent success rate

Supported Processors

Processor	Best For	Settlement Time	Fees
Circle	USDC, fast settlement	Near-instant	0.25%
Shopify Payments	Standard orders	2-3 days	2.9% + $0.30
Payoneer	Cross-border B2B	1-2 days	1-3%
TerraPay	Dual custody	1 day	0.5%
Escrow.com	High-value	3-5 days	1% min

Payment Processing

Process Payment

payment = client.payments.create({
    "customer_id": "cust_abc123",
    "amount": 2050.00,
    "currency": "USD",
    "payment_method": "bank_transfer",
    "order_id": "ord_xyz789"
})

print(f"Payment ID: {payment['id']}")
print(f"Processor: {payment['processor']}")
print(f"Status: {payment['status']}")

Payment Status States

pending → processing → completed
                ↓
          requires_action → failed

Daily Settlement Process

The settlement system runs automatically:

Settlement Status

settlements = client.payments.settlements(
    date="2026-01-11"
)

for settlement in settlements:
    print(f"ID: {settlement['id']}")
    print(f"Amount: ${settlement['amount']}")
    print(f"Processor: {settlement['processor']}")
    print(f"Status: {settlement['status']}")

Circle CCTP V2 (USDC)

Cross-Chain USDC Transfer

# Request USDC settlement
settlement = client.payments.request_usdc_settlement({
    "amount": 10000.00,
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "destination_address": "0x..."
})

CCTP Flow

graph TD
    A[USDC on Ethereum] --> B[Lock USDC]
    B --> C[Circle Attestation]
    C --> D[Mint USDC on Polygon]
    D --> E[Transfer to Merchant]

Dual Custody (TerraPay/Escrow.com)

For high-value transactions:

TerraPay Flow

1. Customer authorizes payment
2. Funds held in TerraPay custody
3. Goods verified by platform
4. Funds released to merchant

Escrow.com Flow

1. Buyer pays to Escrow.com
2. Platform confirms goods shipped
3. Buyer confirms receipt
4. Funds released to seller

Simulation Mode

The platform supports simulation mode for testing settlement flows without real transactions.

Enabling Simulation Mode

1. Navigate to /settings
2. Toggle "Simulation Mode" on
3. This saves your preference to the database

How It Works

When simulation mode is enabled:

1. The server serves the simulation frontend build (/static/profile-sim or /static/market-intel-sim)
2. The frontend calls /api/simulation/* endpoints instead of production endpoints
3. All transactions use mock data and testnet wallets

Delegate Settlement

The Huntrecht Platform supports automated delegate settlement, allowing users to authorize the platform to automatically execute settlements up to a specified maximum amount without requiring QR code authorization for each transaction.

How It Works

1. Enable Delegate: User configures delegate settings in Profile Settings → Auto Settlement
2. Set Maximum: Define the maximum amount (any value > 0, no cap)
3. Select Wallet: Choose which wallet to delegate for settlements
4. Auto-Execute: Settlements within the max amount execute automatically after payment detection

Benefits

• Faster Settlements: No QR code needed for routine settlements
• Customizable Limits: Set any max amount that suits your needs
• Full Control: Revoke access anytime
• Email Notifications: Receive confirmation after each delegate settlement

Configuration

1. Navigate to Profile Settings → Auto Settlement
2. Select your wallet from the dropdown
3. Enter maximum amount (e.g., $500)
4. Click "Enable Delegate"

Delegate Settings

Setting	Description
Wallet	Source wallet for settlements
Max Amount	Maximum auto-settlement amount
Expiry	30 days from enable/renewal
Status	Active/Inactive/Expired

Settlement Flow with Delegate

sequenceDiagram
    participant U as User
    participant A as Auto Settlement
    participant P as Payment System
    participant E as Email Service
    
    U->>A: Initiate Settlement ($300)
    A->>A: Check delegate status
    alt Within Max Amount
        A->>P: Execute automatically
        P->>E: Send confirmation email
        E-->>U: Email notification
    else Exceeds Max Amount
        A->>U: Require QR authorization
    end

Important Notes

• One delegate per user: Only one active delegate allowed at a time
• 30-day expiry: Delegates expire after 30 days, renew anytime
• Per-settlement limit: Each settlement must be within the max amount

Complete Settlement Example

#!/usr/bin/env python3
"""
Complete Payment Settlement Workflow
"""

from huntrecht import HuntrechtClient
import os

def process_payment_settlement(order_id, amount, customer_id):
    client = HuntrechtClient(
        client_id=os.environ.get("HUNTRECHT_CLIENT_ID"),
        client_secret=os.environ.get("HUNTRECHT_CLIENT_SECRET")
    )
    
    # Step 1: Process payment
    print("Step 1: Processing payment...")
    payment = client.payments.create({
        "customer_id": customer_id,
        "amount": amount,
        "currency": "USD",
        "payment_method": "bank_transfer",
        "order_id": order_id
    })
    print(f"  Payment ID: {payment['id']}")
    print(f"  Processor: {payment['processor']}")
    print(f"  Status: {payment['status']}")
    
    # Step 2: Wait for processing
    import time
    print("\nStep 2: Waiting for payment processing...")
    max_attempts = 10
    for i in range(max_attempts):
        time.sleep(2)
        payment = client.payments.get(payment['id'])
        if payment['status'] == 'completed':
            print(f"  ✓ Payment completed")
            break
        elif payment['status'] == 'failed':
            print(f"  ✗ Payment failed")
            return None
        print(f"  Status: {payment['status']} (attempt {i+1})")
    
    # Step 3: Check settlement
    print("\nStep 3: Checking settlement...")
    settlements = client.payments.settlements(
        date="2026-01-11",
        payment_id=payment['id']
    )
    
    for settlement in settlements:
        print(f"  Settlement ID: {settlement['id']}")
        print(f"  Amount: ${settlement['amount']}")
        print(f"  Processor: {settlement['processor']}")
        print(f"  Status: {settlement['status']}")
    
    return payment

# Run workflow
result = process_payment_settlement(
    order_id="ord_xyz789",
    amount=2050.00,
    customer_id="cust_abc123"
)

Webhook Events

Event	Description
payment.completed	Payment successful
payment.failed	Payment failed
payout.created	Payout initiated
payout.completed	Payout received
settlement.completed	Daily settlement complete

Market Making Integration

The settlement system integrates with the Market Making Agent for optimization insights:

Supported Settlements

Settlement Type	Market Making Analysis
Solana	✅ USDT→USDC swap analysis
EVM (Polygon/Base)	✅ Cross-chain arbitrage detection

Analysis Features

• Cross-Chain Arbitrage Detection: Compares prices across Solana, Polygon, Base chains
• Rate Quality Assessment: Evaluates swap execution quality
• Execution Recommendations: Provides optimal slippage and routing suggestions

Data Storage

Analysis results are stored in settlement metadata:

{
  "market_making_analysis": {
    "confidence": 0.75,
    "analysis_type": "cross_chain_arbitrage",
    "detected_pairs": ["solana/polygon"],
    "recommendation": {
      "step": 1,
      "action": "verify_escrow_funding",
      "description": "Verify funds are available in circle_cctp escrow"
    }
  }
}

Next Steps

• Payments API
• Circle Integration
• AI Processor Selection