Documentation

One API for the agent economy

Accept payments from every AI shopping agent — card and stablecoin — through a single integration. Detect agents, route across 7 live protocols, and settle with one flat fee.

REST APIx402 (Crypto)AP2 (Google)MPP (Stripe+Tempo)Visa TAPVisa CLIMC Agent PayWebhooks
The agent economy is here

AI agents are shopping right now. Is your store ready?

ChatGPT handles ~53M shopping queries daily. Google AI, Claude, Perplexity, Amazon Rufus — all sending autonomous buyers to stores. Merchants who accept agent payments capture this wave first.

$60B
AI agent commerce market in 2026
693%
YoY growth in AI referral traffic
31%
higher conversion from AI-referred visits
What changed in 2025–2026
7 protocols now live
AP2 (Google), x402 (Coinbase), MPP (Stripe+Tempo), Visa TAP, Visa CLI, and Mastercard Agent Pay. Agents can transact right now.
Major agents are actively buying
ChatGPT Instant Checkout, Microsoft Copilot Checkout, Perplexity Buy with Pro, Amazon Buy for Me — real money, at scale.
First-mover window is open
Most stores aren't agent-ready. Integrate now and get indexed first, before it's competitive.
Monetise your API access

Build on Shopfi. Earn on every transaction.

Embed Shopfi's full infrastructure in your platform at 10% below direct rates. The difference is yours to keep or pass on.

One API key
Covers all merchants on your platform.
15% lower rate
0.85% flat across all protocols.
White-label
No Shopfi branding required.
What people are building
🏪Multi-merchant platforms
Every store becomes agent-ready. You earn on every AI sale.
🤖AI shopping agents
Route payments across card and stablecoin — one integration.
🛠️Shopify apps
Add agent-payment as a premium feature with your own margin.
📦Headless commerce
Any stack — detect agents, route payments, receive webhooks.
API Reference

Authentication

Base URL your-domain.com/api/v1. All endpoints require a Bearer token. Keys are prefixed sk_live_ (production) or sk_test_ (sandbox). Generate keys in your dashboard.

cURL
curl https://your-domain.com/api/v1/detect \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json"
Discovery

Agent discovery manifest

AI agents discover your payment capabilities via the /.well-known/shopfi.json manifest. No auth required.

GET/.well-known/shopfi.json— Agent discovery manifest
{
  "version": "1.0",
  "protocols": {
    "acp":          { "supported": true, "fee": "1%" },
    "x402":         { "supported": true, "fee": "1%", "network": "eip155:8453" },
    "ap2":          { "supported": true, "fee": "1%" },
    "mpp":          { "supported": true, "fee": "1%" },
    "visa_tap":     { "supported": true, "fee": "1%" },
    "visa_cli":     { "supported": true, "fee": "1%" },
    "mc_agent_pay": { "supported": true, "fee": "1%" }
  }
}
Supported protocols

7 live payment protocols

Shopfi supports 7 live payment protocols across fiat and crypto rails. Shopfi charges 1% as a flat platform fee on all protocols. Network/processor fees from each protocol's payment provider are separate.

x402Crypto · Shopfi 1%
x402 Stablecoin Protocol — Coinbase + Cloudflare
HTTP-native USDC payments on Base network
Network: $0 protocol fee
AP2Card · Shopfi 1%
Agent Payments Protocol — Google (60+ partners)
Mandate-based payments using Verifiable Digital Credentials
Network: ~2.5–3% via PSP
MPPFiat + Crypto · Shopfi 1%
Machine Payments Protocol — Stripe + Tempo
Autonomous machine-to-machine payments for APIs and services
Network: Low Tempo gas
Visa TAPCard · Shopfi 1%
Visa Trusted Agent Protocol — Visa + Cloudflare
Cryptographic agent identity verification on Visa rails
Network: ~1.5–2.5% interchange
Visa CLICrypto · Shopfi 1%
Visa CLI — Command Line Commerce — Visa Crypto Labs
CLI-based payment execution with tokenized Visa credentials
Network: TBD (closed beta)
MC Agent PayCard · Shopfi 1%
Mastercard Agent Pay — Mastercard
Agentic Tokens with programmable purchase intent data
Network: ~1.5–2.5% interchange

Shopfi's platform fee is separate from network/processor fees. Card protocols carry standard interchange + processor fees. Crypto protocols (x402, MPP) have near-zero underlying costs — Shopfi's 1% is typically the only fee.

REST API

Core endpoints

POST/api/v1/detect— Detect agent

Identify if an incoming request is from an AI shopping agent. Returns protocol, trust score, and agent identity.

Request
{
  "headers": {
    "user-agent": "ChatGPT-User/1.0",
    "x-acp-version": "2026-01-30"
  }
}
Response
{
  "isAgent": true,
  "confidence": 90,
  "agentId": "chatgpt",
  "agentName": "ChatGPT",
  "protocol": "ACP",
  "rail": "CARD",
  "trust": 95
}
POST/api/v1/charge— Direct charge

Create a settled transaction directly. Use when you handle payment collection yourself. 1% platform fee on all rails.

Request
{
  "amount": 4999,
  "currency": "usd",
  "protocol": "CARD",
  "agent_id": "chatgpt",
  "agent_name": "ChatGPT",
  "product": "Merino Sweater",
  "order_ref": "ord_abc"
}
Response
{
  "id": "dGVzdC0xMjM",
  "status": "settled",
  "amount": 4999,
  "fee": 25,
  "net": 4974,
  "currency": "usd"
}
POST/api/v1/pay— x402 payment

Universal payment endpoint. Returns 402 with USDC payment requirements. Agent retries with X-PAYMENT header after signing.

Request
{
  "amount": 2999,
  "product": "Widget",
  "description": "Widget — 1x",
  "wallet_address": "0xABC..."
}
Response
// 402 Payment Required
{
  "protocol": "x402",
  "payment_required": {
    "amount": "29.99",
    "receiver": "0xABC...",
    "network": "eip155:8453",
    "asset": "0x833...",
    "nonce": "a1b2c3d4e5f6"
  }
}
GET/api/v1/transactions— List transactions

Paginated transaction history for your merchant account. Supports offset-based pagination.

Request
?limit=50&offset=0
Response
{
  "data": [
    { "id": "...", "amount": 4999,
      "status": "settled", ... }
  ],
  "total": 234,
  "limit": 50,
  "offset": 0
}
Webhooks

Real-time event delivery

Signed POST on every event. Verify with HMAC-SHA256 using your webhook secret (whsec_ prefix). Configure endpoints in your dashboard.

javascript
// Verify signature
const crypto = require('crypto');
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
const valid = signature === expected;
charge.settled
Transaction settled successfully
charge.failed
Payment failed or rejected
charge.refunded
Transaction refunded
Error handling

Status codes

All errors return JSON with an error field. Common status codes:

400Bad request — missing or invalid parameters
401Unauthorized — invalid or missing API key
402Payment Required — x402 payment requirements returned
404Not found — resource does not exist
500Server error — contact support

Ready to accept agent payments?

Generate your API key and go live across every protocol.

Start buildingTry the playground