Documentation

Stripe Cards

Process card payments via Stripe Connect. Money flows directly from consumer's card to provider's Stripe account. AgentPayment fee: 0.5% (Free) / 0.3% (Pro) / 0.2% (Business). Stripe's processing fees are charged separately by Stripe.

Consumer setup — save a card

Or integrate manually — Step 1: Create a SetupIntent to collect card details:

curl -X POST https://AgentPayment/api/v1/payment-methods/card/setup \
  -H "X-API-Key: apn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_your_id"}'

# Returns: client_secret, setup_intent_id, customer_id

Step 2: Use the client_secret with Stripe.js to collect card details, then confirm:

curl -X POST https://AgentPayment/api/v1/payment-methods/card/confirm \
  -H "X-API-Key: apn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_your_id",
    "payment_method_id": "pm_xxx"
  }'

Provider setup — receive card payments

Providers must complete Stripe Connect onboarding once to receive card payments directly:

curl -X POST https://AgentPayment/api/v1/billing/connect/onboard \
  -H "X-API-Key: apn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_your_id"}'

# Returns: onboarding_url — open in browser to complete KYC

Pay with card

payment = client.create_payment(
    from_agent_id="agent_sender_id",
    to_agent_id="agent_receiver_id",
    amount=25.00,
    currency="USD",
    payment_method="stripe_card"
)

ACH Bank Transfer

Bank transfers via Plaid (account linking) + Stripe Connect (processing). Best for high-value settlements. AgentPayment fee: 0.5% (Free) / 0.3% (Pro) / 0.2% (Business). Stripe ACH fees are charged separately by Stripe. Settlement: 2-3 business days.

Consumer setup — link a bank account

Or integrate manually — Step 1: Get a Plaid link token:

curl -X POST https://AgentPayment/api/v1/payment-methods/bank-account/link-token \
  -H "X-API-Key: apn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_your_id"}'

# Returns: link_token — use with Plaid Link to connect bank

Step 2: After user completes Plaid Link, exchange the public token:

curl -X POST https://AgentPayment/api/v1/payment-methods/bank-account \
  -H "X-API-Key: apn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_your_id",
    "public_token": "public-sandbox-xxx",
    "account_id": "account_id_from_plaid"
  }'

Provider setup — receive ACH payments

Same as card — complete Stripe Connect onboarding once (see Provider Setup above).

Pay with ACH

payment = client.create_payment(
    from_agent_id="agent_sender_id",
    to_agent_id="agent_receiver_id",
    amount=500.00,
    currency="USD",
    payment_method="bank"
)

External Payments (Accountless)

Any AI agent — even one with no AgentPayment account — can pay an invoice from a registered provider. This is the Accountless Payment Protocol pattern: the payer discovers payment requirements, sends funds, and receives an access token to prove payment.

How it works

1. Provider (registered) creates an invoice as normal
2. Provider shares the invoice_id with the external payer
3. External payer fetches payment details — no API key needed
4. External payer sends ETH / card / ACH payment
5. Platform issues a signed access_token
6. Payer passes access_token to provider to unlock the service
7. Provider verifies token — no API key needed to verify

Step 1 — Provider creates invoice

from agent_payment_sdk import AgentPaymentClient

provider = AgentPaymentClient(api_key="your_api_key")

invoice = provider.create_invoice(
    to_agent_id=None,          # no consumer account required
    amount=5.00,
    currency="USD",
    payment_rail="crypto",
    description="AI data feed access — 1 hour"
)
invoice_id = invoice["invoice_id"]
# Share invoice_id with the external payer

Step 2 — External payer fetches payment info

No SDK or account needed. Any HTTP client works.

# No API key required
info = AgentPaymentClient.get_invoice_pay_info(
    invoice_id=invoice_id,
    base_url="https://AgentPayment"
)
# Returns: amount, currency, receiver_wallet, accepted_rails
print(info["accepted_rails"])
# [{"rail": "crypto", "receiver_wallet": "0x...", "network": "base-mainnet"}]

Public — no authentication required. Returns payment details.

Step 3 — External payer pays (crypto)

from agent_payment_sdk import AgentPaymentClient

# Payer has NO AgentPayment account — just an ETH wallet
receipt = AgentPaymentClient.pay_external_invoice(
    invoice_id=invoice_id,
    rail="crypto",
    private_key="0x...",       # payer's ETH private key
    base_url="https://AgentPayment"
)

access_token = receipt["access_token"]
# Pass access_token to the provider to unlock the service

Step 3 (alternative) — External payer pays (card)

receipt = AgentPaymentClient.pay_external_invoice(
    invoice_id=invoice_id,
    rail="card",
    payment_method_id="pm_...",   # Stripe Payment Method ID from Stripe.js
    payer_email="agent@example.com",
    base_url="https://AgentPayment"
)

Public — no authentication required.

Step 4 — Provider verifies access token

# Provider verifies before granting service access
result = AgentPaymentClient.verify_external_payment(
    invoice_id=invoice_id,
    access_token=token_from_payer,
    base_url="https://AgentPayment"
)

if result["valid"]:
    grant_access_to_service()
    print(f"Verified — payer: {result['payer_wallet']}")

Public — no authentication required. Returns {"valid": true} if payment confirmed.

Partial & Installment Payments

Invoices can be paid in multiple installments. A consumer with a billing rule capped below the invoice amount automatically pays their maximum — the remainder stays pending for later.

How partial payments work

1. Provider creates invoice for $100
2. Consumer has billing rule max $40 — auto-pays $40 instantly
3. Invoice status becomes PARTIAL_PAID, amount_remaining: 60
4. Consumer raises their limit or manually pays the rest
5. Invoice becomes PAID when fully settled

Check invoice balance

invoice = provider.get_invoice(invoice_id)
print(invoice["amount_paid"])       # 40.0
print(invoice["amount_remaining"])  # 60.0
print(invoice["status"])            # PARTIAL_PAID
print(invoice["partial_payments"])  # 1

Pay the remaining balance

# Consumer pays the full remaining balance
consumer = AgentPaymentClient(api_key="consumer_api_key")
result = consumer._request(
    "POST",
    f"/api/v1/invoices/{invoice_id}/pay-remaining"
)
print(result["status"])  # PAID

Pay a specific partial amount

# Pay only $25 of the $60 remaining
result = consumer._request(
    "POST",
    f"/api/v1/invoices/{invoice_id}/pay-remaining",
    json={"partial_amount": 25.00}
)
print(result["amount_remaining"])  # 35.0

Authenticated — requires consumer API key. Optional body: {"partial_amount": float}

List invoices with payment progress

# See all invoices with paid/remaining amounts
invoices = consumer._request("GET", "/api/v1/invoices")
for inv in invoices["invoices"]:
    print(f"{inv['invoice_id']}: "
          f"${inv['amount_paid']} paid, "
          f"${inv['amount_remaining']} remaining, "
          f"status: {inv['status']}")

Agent-to-Agent Billing

The pull payment model — provider agents autonomously invoice consumer agents, which auto-approve and pay instantly based on billing rules. Zero human intervention required.

How it works

1. Consumer agent sets an auto-approval billing rule once (max amount + preferred rail)
2. Provider agent serves a request and creates an invoice against the consumer
3. System checks billing rule → if approved, payment processes instantly
4. Both agents receive confirmation with transaction ID and tx hash

Step 1 — Consumer sets billing rule

consumer = AgentPaymentClient(api_key="apn_consumer_key")

rule = consumer.set_billing_rule(
    max_amount=10.00,           # auto-approve invoices up to $10
    preferred_rail="crypto",    # crypto | card | bank
    approved_provider_id="agent_provider_id"
)
print(rule["message"])  # Auto-approve invoices from agent_provider_id up to $10.0

Step 2 — Provider creates invoice

provider = AgentPaymentClient(api_key="apn_provider_key")

invoice = provider.create_invoice(
    to_agent_id="agent_consumer_id",
    amount=3.00,
    description="API usage — 150 requests @ $0.02/req",
    payment_rail="crypto"
)

print(invoice["status"])      # PAID (auto-approved instantly)
print(invoice["invoice_id"])   # uuid
print(invoice["paid_at"])      # 2026-03-17T...

Recurring Billing

Providers register a billing schedule once — the platform fires it automatically at the chosen interval. Two models: webhook-based (Model A) or fully autonomous (Model B).

Model A — Webhook-Based

Platform fires a webhook to your callback_url at each interval. You calculate actual usage and call POST /invoices with the real amount.

provider = AgentPaymentClient(api_key="apn_provider_key")

schedule = provider.create_recurring_billing(
    consumer_id="agent_consumer_id",
    frequency="1h",                # 30m, 1h, 6h, 1d, 7d, 30d
    payment_rail="CRYPTO",
    callback_url="https://your-service.com/billing-webhook",
    max_per_period=100.00,         # safety cap per cycle
    description="API usage billing"
)

At each interval, your callback_url receives:

{
  "event": "billing_due",
  "recurring_id": "f55ecdcf-...",
  "provider_id": "agent_xyz",
  "consumer_id": "agent_abc",
  "period_start": "2026-04-04T15:00:00",
  "period_end": "2026-04-04T16:00:00",
  "payment_rail": "CRYPTO",
  "max_per_period": 100.0
}

Then create an invoice for the actual usage:

# In your webhook handler:
usage = calculate_usage(period_start, period_end)

invoice = provider.create_invoice(
    to_agent_id="agent_consumer_id",
    amount=usage,
    payment_rail="CRYPTO",
    description="API usage 15:00-16:00 UTC"
)
# Consumer billing rule auto-pays if within limit

Model B — Fully Autonomous

Platform calls your usage_endpoint at each interval, creates the invoice, and triggers auto-payment. Zero involvement after setup.

schedule = provider.create_recurring_billing(
    consumer_id="agent_consumer_id",
    frequency="1h",
    payment_rail="CRYPTO",
    usage_endpoint="https://your-service.com/usage",
    max_per_period=100.00,
    description="API usage billing"
)
# AgentPayment auto-generates a secure token — store it once:
token = schedule["usage_auth_token"]  # e.g. "a3f9c2e1d4b7..."

Your usage_endpoint receives a POST and must return:

# Platform sends:
{
  "recurring_id": "f55ecdcf-...",
  "consumer_id": "agent_abc",
  "period_start": "2026-04-04T15:00:00",
  "period_end": "2026-04-04T16:00:00"
}

# Your response:
{ "amount": 42.50 }  # Return 0 to skip invoicing this period