fypay-proxy

Zero-code payment proxy sidecar for AgentPay protocol.

Put fypay-proxy in front of any HTTP API — it handles quoting, authorization verification, capture, and void automatically. Your business code stays untouched.

Quick Start

# Install globally
npm install -g fypay-proxy

# Generate SM2 signing key
fypay-proxy keygen --out seller.key

# Create a pricing template (quote.json)
cat > quote.json <<EOF
{
  "seller_id": "sel:your_seller_id",
  "currency": "CNY",
  "authorized_amount": 0.01,
  "recipient": "acct:your_account",
  "key_id": "kid:xxx"
}
EOF

# Start the proxy in front of your API
fypay-proxy serve \
  --target http://127.0.0.1:3000 \
  --signing-key file:./seller.key \
  --quote-template ./quote.json \
  --seller-id sel:your_seller_id \
  --key-id kid:xxx

How It Works

Buyer Agent
    │
    ├─ No AgentPay-Authorization header
    │  └─ fypay-proxy returns 402 + AgentPay-Quote
    │     (your API is never called)
    │
    ├─ Invalid / expired authorization
    │  └─ fypay-proxy returns 403
    │     (your API is never called)
    │
    └─ Valid authorization
       └─ fypay-proxy forwards request to your API
          └─ 2xx → adds AgentPay-CaptureRequest header
          └─ non-2xx → issues void (refund)

Your business API has zero awareness of AgentPay — the proxy handles everything.

Commands

| Command | Description | |---------|-------------| | fypay-proxy serve [options] | Start the reverse proxy sidecar | | fypay-proxy keygen [options] | Generate SM2 key pair + key_id | | fypay-proxy quote-sign [options] | Debug tool: sign a Quote manually |

Serve Options

| Flag | Env Var | Default | Description | |------|---------|---------|-------------| | --target <url> | FYPAY_TARGET | — | Upstream API address (required) | | --listen <host:port> | FYPAY_LISTEN | 0.0.0.0:8080 | Public listen address | | --admin <host:port> | FYPAY_ADMIN_LISTEN | 127.0.0.1:9090 | Admin endpoint | | --mode <mode> | FYPAY_MODE | production | mock for local testing | | --seller-id <id> | FYPAY_SELLER_ID | — | Seller ID (required) | | --key-id <id> | FYPAY_KEY_ID | — | Key ID from keygen (required) | | --signing-key <src> | FYPAY_SIGNING_KEY | — | file:/path or env:VAR (required) | | --quote-template <file> | FYPAY_QUOTE_TEMPLATE | — | Quote JSON template (required) | | --platform-endpoint <url> | FYPAY_PLATFORM_ENDPOINT | — | AgentPay platform URL | | --void-policy <policy> | FYPAY_VOID_POLICY | non-2xx | When to void | | --log-level <level> | FYPAY_LOG_LEVEL | info | Log verbosity |

Mock Mode

Use --mode=mock for local development without a real AgentPay platform:

fypay-proxy serve --mode=mock --target http://127.0.0.1:3000 ...

# The admin endpoint provides a mock authorization signer:
curl -X POST http://127.0.0.1:9090/mock/sign-authorization \
  -H 'content-type: application/json' \
  -d '{"endpoint":"/api/data","method":"GET"}'

Requirements

• Node.js >= 20

License

MIT