Integrating Paitify with MCP Payment Servers: A Step-by-Step Guide
The MCP ecosystem has grown fast: thousands of public servers, and tool-calling SDKs downloaded tens of millions of times. A growing slice of those servers expose payment operations directly — charge a card, create an invoice, issue a payout. That's useful. It's also the first category of MCP tool where "the agent called it successfully" and "the agent should have been allowed to call it" are genuinely different questions.
This guide covers the mechanical part: how to sit Paitify's policy engine between an MCP payment tool call and the moment it actually executes, using a real request/response shape rather than pseudocode. If you want the conceptual case for why this layer needs to exist at all, see MCP and the Future of Agent-Native Payments — this post picks up where that one leaves off.
Why OAuth scope isn't a spend policy
MCP's authorization flow proves a client holds a valid, appropriately-scoped credential to call a given tool. That's an identity and permission question — can this client invoke charge? It has no opinion on the question that actually matters for money: should this specific charge, for this amount, to this merchant, right now, be allowed?
Those two questions don't collapse into each other. A credential scoped to call a payment tool is still just as valid whether the agent tries to charge $12 or $12,000, once or a thousand times in a minute. Pre-execution policy enforcement — transaction limits, daily budgets, merchant allowlists, velocity checks — is a separate layer that has to sit in front of the payment call, not something OAuth scope can stand in for.
Where Paitify sits in the flow
Paitify never moves money and isn't a payment rail itself — it's the governance layer that decides whether a payment rail should be allowed to run:
- Your agent (or the orchestration code around it) decides it wants to call a payment MCP tool — e.g. Stripe MCP's charge operation.
- Before that tool call executes, your code calls Paitify's
authorizeendpoint with the transaction details. - Paitify evaluates the request against the agent's active policy — per-transaction limits, daily budget, merchant/MCC allowlists — and returns a state.
- If the state is approved, proceed with the actual payment MCP call. If it's declined, the charge never happens.
- Every decision — approved, declined, or escalated to a human — is written to an immutable audit entry, independent of whether the agent tells you the truth about what it did.
This works the same way regardless of which payment MCP server sits on the other side — Stripe MCP, Salesforce Commerce MCP, or anything else that speaks MCP. Paitify's check happens in your orchestration layer, not inside the payment server, so it's rail-agnostic by construction.
Step-by-step: gating a Stripe MCP charge
The integration zone (/v1/integration/*) is the machine-callable surface — authenticated with an API key (X-API-Key), never a user session. Here's the pattern for wrapping a payment MCP tool call with a Paitify check:
const PAITIFY_API_BASE = "https://api.paitify.io/v1/integration";
const PAITIFY_API_KEY = process.env.PAITIFY_API_KEY!;
type AuthorizeResponse = {
authorizationId: string;
state: string; // "CAPTURED" | "AUTHORIZED" | "REQUIRES_APPROVAL" | "DECLINED_BY_POLICY" | ...
jwtToken: string | null;
reasonCode: string | null;
requiresHumanApproval: boolean;
};
async function authorizeSpend(input: {
agentId: string;
amount: number;
currency: string;
merchantName: string;
mccCode?: string;
idempotencyKey: string;
}): Promise<AuthorizeResponse> {
const res = await fetch(`${PAITIFY_API_BASE}/authorize`, {
method: "POST",
headers: {
"X-API-Key": PAITIFY_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(input),
});
return res.json();
}
// Called from your agent's tool-orchestration layer, BEFORE the Stripe MCP
// charge tool is invoked — not after, and not in parallel.
async function chargeWithPolicyGate(charge: {
agentId: string;
amountUsd: number;
merchantName: string;
mccCode: string;
// A caller-supplied ID for this logical charge, stable across retries of
// the same operation (e.g. the id of the order/task that triggered it).
// Must NOT be regenerated on each retry attempt.
idempotencyKey: string;
}) {
const authorization = await authorizeSpend({
agentId: charge.agentId,
amount: charge.amountUsd,
currency: "USD",
merchantName: charge.merchantName,
mccCode: charge.mccCode,
idempotencyKey: charge.idempotencyKey,
});
if (authorization.state === "DECLINED_BY_POLICY") {
throw new Error(`Blocked by policy: ${authorization.reasonCode}`);
}
if (authorization.state === "REQUIRES_APPROVAL") {
// Held for a human reviewer in the dashboard. Poll
// GET /v1/integration/authorizations/{id}, or subscribe to the
// authorization.approved / authorization.declined_by_human webhook,
// rather than looping here synchronously.
return { status: "pending_approval", authorizationId: authorization.authorizationId };
}
// state is CAPTURED or AUTHORIZED — approved. Now, and only now, call the
// actual payment MCP tool (e.g. Stripe MCP's charge operation).
const chargeResult = await stripeMcpClient.callTool("create_charge", {
amount: charge.amountUsd * 100,
currency: "usd",
description: charge.merchantName,
});
// If the policy's mode is EXPLICIT (state === "AUTHORIZED"), the spend is
// only reserved, not yet committed — capture it once the Stripe charge
// actually succeeds. In AUTO mode (state === "CAPTURED") this step isn't
// needed; it already happened as part of authorize.
if (authorization.state === "AUTHORIZED") {
await fetch(`${PAITIFY_API_BASE}/authorize/${authorization.authorizationId}/capture`, {
method: "POST",
headers: { "X-API-Key": PAITIFY_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ agentId: charge.agentId }),
});
}
return { status: "captured", authorizationId: authorization.authorizationId, chargeResult };
}
Two details worth calling out:
- The
idempotencyKeymatters more here than in a typical API call — and it has to stay stable across retries of the same logical charge. Agent loops retry. A duplicateauthorizecall with the same key returns the original decision instead of re-evaluating policy, so derive the key from something that doesn't change between retry attempts — the id of the order or task that triggered the charge, for example — never from a timestamp or anything else regenerated per call. A key that changes on every retry (e.g.Date.now()) defeats the dedup entirely and lets a retried authorize silently consume budget twice for the same intended charge. jwtTokenisn't proof the authorization is still valid at execution time — only that it was valid when issued, for up to 15 minutes. If there's any meaningful delay betweenauthorizeand actually calling the payment tool (a queued job, a human-approval wait, a retry backoff), re-check live state viaGET /v1/integration/authorizations/{id}immediately before executing. A cancellation or human denial changes state without revoking the token itself.
Configuring per-agent policy
The authorize call above evaluates against whatever policy is currently active for agentId — that's dashboard configuration, not something this integration code sets. For each agent you register:
- A max-per-transaction limit and a daily/monthly budget
- Allowed merchants and MCC codes (e.g. restrict a procurement agent to MCC
7372— computer programming — and block everything else) - AUTO mode (approved requests capture immediately) vs. EXPLICIT mode (approved requests reserve, and your code calls
/captureonce the downstream payment actually succeeds — the pattern used above) - An approval threshold above which a human reviewer signs off before anything clears
Scope policies tightly per agent rather than sharing one broad policy across every agent that touches payment MCP tools — an agent that only ever needs to pay one SaaS vendor shouldn't hold a policy that also permits arbitrary merchants.
Audit log integration
Every authorize call — approved, declined, or escalated — writes an immutable audit entry, regardless of what the agent or the payment MCP server reports back. Two ways to pull that into your own observability stack:
- Poll
GET /v1/integration/authorizations/{id}for the live state of a specific authorization. - Subscribe to webhooks (dashboard → Settings → Webhooks) for a real-time feed of
authorization.approved,authorization.denied,authorization.requires_approval,authorization.captured,authorization.cancelled,authorization.reversed, andauthorization.declined_by_humanevents, each HMAC-signed so you can verify delivery before trusting it.
Either path gives you a queryable record that's independent of the agent's own account of what happened — the thing that turns "the agent said it charged the right amount" into something you can actually verify after the fact.
Getting started
None of the above requires a paid plan to try. The Free tier includes real policy enforcement and a 7-day audit log, enough to wire up exactly the flow in this guide against a test agent before you decide how far to take it. Get started free, or see the full API and MCP reference for every endpoint used here.