Integrations
Two modes. One platform.
PayFence gives you two integration paths — reverse proxy for zero-code deployment, and middleware for maximum control. Both share the same dashboard, billing, and analytics.
Side-by-side comparison
| Feature | Reverse Proxy | Middleware |
|---|---|---|
| Code changes | None | One API call per request |
| Agent-facing URL | PayFence gateway URL | Your own domain |
| Added latency | 10–30 ms | ~5 ms |
| Origin protection | HMAC-signed requests | Your server validates |
| Setup time | Under 5 minutes | 15–30 minutes |
| Custom response logic | Limited (headers, status) | Full control |
| Best for | Fast launch, full isolation | Existing APIs, custom flows |
Zero code. Full protection.
In proxy mode, agents call your PayFence gateway URL instead of your origin. PayFence validates the API token, checks quota, and forwards the request to your origin with an HMAC-signed header. Your origin rejects anything without a valid signature.
This means your origin server is completely hidden from the public internet. There is no way for agents to bypass the paywall because they never learn your real origin URL, and even if they did, the origin would reject unsigned requests.
Request Flow
gateway.payfence.com/your-siteExample: Agent calls your gateway
curl -X GET \
https://gateway.payfence.com/your-site/v1/flights \
-H "Authorization: Bearer pf_live_abc123" \
-H "Content-Type: application/json"
# 200 OK — quota decremented, response from origin
# 402 Payment Required — quota exceeded
# 401 Unauthorized — invalid tokenWhat your origin receives
GET /v1/flights HTTP/1.1
Host: api.yoursite.com
X-PayFence-Signature: sha256=a1b2c3d4...
X-PayFence-Token-Id: tok_abc123
X-PayFence-Plan: pro
X-PayFence-Remaining: 94521Example: Authorize in your server
// Middleware: validate token with PayFence
const res = await fetch(
"https://api.payfence.io/v1/authorize",
{
method: "POST",
headers: {
"Authorization": "Bearer pf_sk_your_secret",
"Content-Type": "application/json",
},
body: JSON.stringify({
token: req.headers["authorization"],
method: req.method,
path: req.path,
}),
}
);
const { allowed, remaining, plan } = await res.json();
if (!allowed) {
return res.status(402).json({
error: "quota_exceeded",
upgrade_url: "https://..."
});
}
// Process request normally
return handleRequest(req, res);Authorization response
{
"allowed": true,
"token_id": "tok_abc123",
"plan": "pro",
"remaining": 94521,
"limit": 100000,
"resets_at": "2025-02-01T00:00:00Z"
}Your domain. Full control.
In middleware mode, agents call your API directly at your own domain. Before processing any request, your server makes a single POST to PayFence's /v1/authorize endpoint. PayFence returns whether the request is allowed, along with quota information.
This approach gives you complete control over the request and response lifecycle. You decide what error message to return, what headers to set, and how to handle edge cases. PayFence only provides the authorization decision.
Request Flow
api.yoursite.com/v1/flightsPOST /v1/authorizeallowed: true/falseWhich should I choose?
Most teams start with proxy mode and graduate to middleware when they need finer control.
Choose Proxy if you…
- •Want to launch as fast as possible with no code changes
- •Need your origin completely hidden from the public internet
- •Are building a new API and want monetization from day one
- •Prefer PayFence to handle token validation and quota enforcement
- •Can tolerate 10–30 ms additional latency per request
Choose Middleware if you…
- •Have an existing API and want to keep your domain and URL structure
- •Need full control over error responses and request handling
- •Want the lowest possible added latency (~5 ms)
- •Already have authentication and want to layer billing on top
- •Need custom logic before or after the authorization check
Not sure? Start with proxy mode. You can switch to middleware later without changing your plans, billing, or consumer tokens.