PayPilot — Payment Processing for AI Agents

Accept payments, send invoices, issue refunds, and track sales — all through conversation.

Setup

PayPilot connects to a hosted API proxy at https://paypilot.agms.com. On first use, check for credentials:

cat ~/.config/paypilot/config.json

If no config exists, guide the user through setup:

1. Register on the PayPilot proxy:

curl -s "https://paypilot.agms.com/v1/auth/register" -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"BUSINESS_NAME","email":"EMAIL","password":"PASSWORD"}'

1. Login to get an access token:

curl -s "https://paypilot.agms.com/v1/auth/login" -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"EMAIL","password":"PASSWORD"}'

1. Configure the payment gateway key:

curl -s "https://paypilot.agms.com/v1/auth/configure" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"gateway_key":"YOUR_GATEWAY_KEY"}'

1. Save credentials locally:

mkdir -p ~/.config/paypilot
cat > ~/.config/paypilot/config.json << 'EOF'
{
  "api_url": "https://paypilot.agms.com",
  "email": "merchant@example.com",
  "token": "jwt_token_here"
}
EOF
chmod 600 ~/.config/paypilot/config.json

Note: The password is used only during registration and login to obtain a JWT. It is never stored in the config file or read from environment variables.

If the user doesn't have a gateway account, start the onboarding process:

1. Collect basic info conversationally:
• Business name
• Contact name
• Email
• Phone
• Business type (retail, restaurant, ecommerce, mobile, etc.)

1. Save the lead to our system:

curl -s "https://paypilot.agms.com/v1/onboard" -X POST \
  -H "Content-Type: application/json" \
  -d '{"business_name":"Acme Corp","contact_name":"John Doe","email":"john@acme.com","phone":"555-1234","business_type":"retail"}'

1. Send them the full application link to complete and e-sign:

> "Great! To finish your application, complete the form here: https://agms.com/get-started/

> It takes about 5-10 minutes. You'll need your business address, Tax ID, and banking info. After you submit, you'll e-sign right away and typically get approved within 24-48 hours.

> Once approved, come back and I'll set up your payment processing in seconds."

Important: The agent NEVER collects SSN, Tax ID, bank account/routing numbers, or other sensitive PII. Those go through the secure AGMS form only.

Authentication

All payment endpoints require a JWT bearer token. Load config and set headers:

CONFIG=$(cat ~/.config/paypilot/config.json)
API=$(echo $CONFIG | jq -r '.api_url')
TOKEN=$(echo $CONFIG | jq -r '.token')
AUTH="Authorization: Bearer $TOKEN"

If a request returns 401, re-login and update the saved token.

To refresh an expired token:

Prompt the user for their password — never store it or read it from environment variables:

# Re-login
LOGIN=$(curl -s "$API/v1/auth/login" -X POST \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"$(echo $CONFIG | jq -r '.email')\",\"password\":\"$USER_PASSWORD\"}")
NEW_TOKEN=$(echo $LOGIN | jq -r '.access_token')

# Update config
TMP=$(mktemp)
chmod 600 "$TMP"
jq --arg t "$NEW_TOKEN" '.token = $t' ~/.config/paypilot/config.json > "$TMP" && mv "$TMP" ~/.config/paypilot/config.json
chmod 600 ~/.config/paypilot/config.json

Core Commands

Charge / Sale

Process a payment using a vaulted card token. Never handle raw card numbers.

curl -s "$API/v1/payments/charge" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"amount":500.00,"token":"VAULT_ID","description":"Consulting — January"}'

Enable 3D Secure for higher-value or flagged transactions:

curl -s "$API/v1/payments/charge" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"amount":2500.00,"token":"VAULT_ID","description":"Premium service","three_d_secure":true}'

The response includes risk assessment and verification:

{
  "transaction_id": "123",
  "status": "complete",
  "amount": 2500,
  "risk": { "score": "low", "flags": [] },
  "verification": { "avs": "Y", "cvv": "M" },
  "three_d_secure": true
}

Send Invoice / Payment Link

curl -s "$API/v1/payments/invoice" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"amount":500.00,"email":"john@example.com","description":"Consulting — January"}'

Refund

# Full refund
curl -s "$API/v1/payments/refund" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"transaction_id":"TXN_ID"}'

# Partial refund
curl -s "$API/v1/payments/refund" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"transaction_id":"TXN_ID","amount":50.00}'

Void (same-day cancel)

curl -s "$API/v1/payments/void" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"transaction_id":"TXN_ID"}'

View Transactions

curl -s "$API/v1/transactions" -H "$AUTH" | jq .

Sales Summary

curl -s "$API/v1/transactions/summary" -H "$AUTH" | jq .

Customer Vault (Tokenize Cards Securely)

Store a card securely — returns a vault token. The customer enters card details through a secure form; raw card data never touches the agent.

curl -s "$API/v1/vault/add" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"first_name":"John","last_name":"Smith","email":"john@example.com"}'

Charge a Vaulted Card

curl -s "$API/v1/vault/charge" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"vault_id":"VAULT_ID","amount":99.00,"description":"Monthly service"}'

Recurring Billing

# Create subscription
curl -s "$API/v1/subscriptions" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"vault_id":"VAULT_ID","plan_id":"monthly_99","amount":99.00,"interval":"monthly"}'

# Cancel subscription
curl -s "$API/v1/subscriptions/SUB_ID" -X DELETE -H "$AUTH"

Fraud Detection & Rules

# View 30-day fraud analytics
curl -s "$API/v1/fraud/summary" -H "$AUTH" | jq .

# List active fraud rules
curl -s "$API/v1/fraud/rules" -H "$AUTH" | jq .

# Create a fraud rule (flag transactions over $5000)
curl -s "$API/v1/fraud/rules" -X POST \
  -H "Content-Type: application/json" -H "$AUTH" \
  -d '{"rule_type":"max_amount","threshold":"5000","action":"flag"}'

# Supported rule types: max_amount, min_amount, velocity_limit
# Actions: flag (alert), block (reject), review (hold)

# View a specific rule (if supported)
curl -s "$API/v1/fraud/rules/RULE_ID" -H "$AUTH" | jq .

# Delete a rule
curl -s "$API/v1/fraud/rules/RULE_ID" -X DELETE -H "$AUTH"

Note: rule updates are not supported. Delete and recreate the rule instead.

Example response from creating a rule:

{
  "rule_id": "rule_123",
  "rule_type": "max_amount",
  "threshold": "5000",
  "action": "flag",
  "status": "active",
  "created_at": "2026-03-15T00:00:00Z"
}

When reporting fraud stats:

> "🛡️ Last 30 days: 45 transactions, 0 flagged, 0 blocked. 1 active rule (max $5,000). Fraud rate: 0.00%"

Security Rules

• NEVER ask for, log, or store raw credit card numbers
• NEVER include card numbers in conversation history or memory files
• ALWAYS use payment links or customer vault tokens for charges
• ALWAYS use HTTPS — the proxy enforces TLS
• API tokens and gateway keys must stay in config files, never in chat
• The proxy encrypts gateway keys at rest (AES-256-GCM)
• Rate limited: 60 requests/min global, 5/min on auth endpoints

Error Handling

• 401 Unauthorized: re-login, update the saved token, then retry.
• 400 Bad Request: validate request body and log the error message.
• 429 Rate Limited: 60 req/min global, 5/min auth. Back off and retry.
• 5xx Server Error: retry with exponential backoff.
• Network errors: verify HTTPS connectivity, then retry.

Response Patterns

When a payment succeeds:

> "✅ Payment of $500.00 processed. Transaction ID: abc123."

When sending an invoice:

> "📧 Payment link for $500.00 sent to john@example.com."

When a payment fails:

> "❌ Payment declined. Want to try a different method or send a payment link instead?"

When checking sales:

> "📊 This month: 23 transactions · $4,750 in sales · 2 refunds ($150) · Net: $4,600"

API Reference

For detailed gateway API documentation, see references/gateway-api.md.

For payment flow diagrams, see references/payment-flows.md.

For PCI compliance guidelines, see references/pci-compliance.md.

Discovery

AI agents and bots can discover PayPilot capabilities automatically:

• OpenAPI Spec: https://paypilot.agms.com/openapi.json
• AI Plugin Manifest: https://paypilot.agms.com/.well-known/ai-plugin.json
• LLM Resource Index: https://paypilot.agms.com/llms.txt
• Landing Page: https://agms.com/paypilot/
• ClawHub: https://clawhub.ai/agmsyumet/paypilot-agms