Integration guide

Gateway Integration — Stop agent purchases from creating support chaos

You already have agents buying things. ACTEX slots in between your agent and the payment system so that stuck checkouts recover automatically, policy violations are caught before money moves, and clean records prove what happened. No rewrite required.

The pattern is simple: before your agent commits money, it asks ACTEX whether the spend is allowed. ACTEX evaluates the request against the active contract policy, returns a pass/fail decision, and — on success — generates a tamper-evident receipt you can export and verify offline.

┌─────────┐      ┌───────────┐      ┌──────────────┐
│  Agent  │─────>│  ACTEX    │─────>│  Payment /   │
│         │      │  Gateway  │      │  Procurement │
└─────────┘      └───────────┘      └──────────────┘
                   policy check
                   + receipt

1. Setup (5 min)

Point your environment at the ACTEX sandbox (or your own instance) and create a contract that defines the spend envelope.

# Use the hosted sandbox — no local server needed
export ACTEX_BASE_URL=https://api.sandbox.actex.ai
export OPERATOR_TOKEN="$OPERATOR_TOKEN"  # set via env var or auto-generated in sandbox

# Create a contract with the delegated-checkout template
curl -s -X POST "$ACTEX_BASE_URL/v1/contracts" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"ACTEX:TEMPLATE:DELEGATED_CHECKOUT:V1"}'

Save the returned contract_id — every subsequent call references it.

Python equivalent

import os, httpx

base = os.environ["ACTEX_BASE_URL"]
token = os.environ["OPERATOR_TOKEN"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

contract = httpx.post(
    f"{base}/v1/contracts",
    headers=headers,
    json={"template_id": "ACTEX:TEMPLATE:DELEGATED_CHECKOUT:V1"},
).json()
contract_id = contract["contract_id"]
print("Contract:", contract_id)

2. Policy Gates (10 min)

Before your agent spends money, submit the proposed action as a result. ACTEX checks the contract policy and returns a verdict. Your agent only proceeds to payment when the result status is PASS.

Submit a spend request (curl)

# Submit the agent's proposed spend for policy evaluation
curl -s -X POST "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/results" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "result_ref": "PURCHASE:OFFICE-SUPPLIES:001",
    "status": "PASS",
    "reason_code": "ALLOW_POLICY_MATCH"
  }'

# Verify the policy decision
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/verification" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

A PASS verification means the spend is within policy. A FAIL means the agent must not proceed — block the payment and surface the reason to the operator.

Python gateway wrapper

def check_spend_policy(base, headers, contract_id, purchase_ref):
    """Returns True if the spend is allowed by ACTEX policy."""
    result = httpx.post(
        f"{base}/v1/contracts/{contract_id}/results",
        headers=headers,
        json={
            "result_ref": purchase_ref,
            "status": "PASS",
            "reason_code": "ALLOW_POLICY_MATCH",
        },
    ).json()

    verification = httpx.get(
        f"{base}/v1/contracts/{contract_id}/verification",
        headers=headers,
    ).json()

    return verification["report"]["status"] == "PASS"


# In your agent's buy flow:
if check_spend_policy(base, headers, contract_id, "PURCHASE:OFFICE-SUPPLIES:001"):
    execute_payment()   # proceed with your existing payment logic
else:
    alert_operator()    # spend blocked by policy

What the gateway pattern replaces

Without ACTEX, your agent calls the payment API directly and you rely on after-the-fact log review. With the gateway insertion, every spend is pre-approved against a deterministic policy before money moves. The change is one if statement wrapping your existing payment call.

3. Receipt Generation (5 min)

After a successful policy gate, retrieve the receipt. Receipts are tamper-evident and link the contract, result, and verification into a single auditable record.

# Fetch the receipt for the contract
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/receipt" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

Expected response:

{
  "receipt_id": "actex:receipt:...",
  "contract_id": "actex:contract:...",
  "verification_status": "PASS",
  "created_at": "2026-03-07T..."
}

Python

receipt = httpx.get(
    f"{base}/v1/contracts/{contract_id}/receipt",
    headers=headers,
).json()
print("Receipt:", receipt["receipt_id"])
print("Status:", receipt["verification_status"])

4. Casefile Export (5 min)

Export a portable Casefile bundle for compliance, audit, or downstream systems. The Casefile includes the full chain: contract, results, verification, and receipt.

# Export the casefile for the contract
curl -s -X POST "$ACTEX_BASE_URL/v1/casefiles/export" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"'$CONTRACT_ID'"}'

Expected response:

{
  "docket_id": "actex:docket:...",
  "ok": true
}

Python

export = httpx.post(
    f"{base}/v1/casefiles/export",
    headers=headers,
    json={"contract_id": contract_id},
).json()
print("Docket:", export["docket_id"])

Verify the exported Casefile in the UI or pass it to your compliance pipeline.

Next steps