Vopify MCP Integration

Vopify exposes a Model Context Protocol (MCP) endpoint that allows AI assistants and automation tools to run payee verifications, retrieve verification history, and check account status on behalf of authenticated users. Compatible with Claude, ChatGPT, n8n, and any MCP-compatible tool.

Endpoint:   https://vopify.io/mcp
Transport:  Streamable HTTP (MCP spec 2025-06-18)
Auth:       OAuth 2.1 — Bearer token

Authentication

Vopify's MCP uses OAuth 2.1 with bearer tokens issued by Vopify's sign-in service. When connecting a new tool, you will be redirected to log in with your Vopify account credentials. The resulting bearer token is scoped to your account — all verifications consume credits from your balance.

Token audience: authenticated

Available tools

Vopify exposes 3 tools via MCP. All tools return the standard MCP CallToolResult shape — a content array where content[0].text contains the JSON-stringified payload, and a structuredContent object containing the same data parsed.

typescript
{
  content: [{ type: "text", text: string }],  // JSON-stringified payload
  structuredContent?: object,                  // same payload as parsed object
   isError?: boolean                            // true for tool-level failures where set
}

verify_payee

Runs a real-time Verification of Payee check against the specified payment network and account details. Attempts to deduct 1 credit only when a verification result is returned (errorCategory: "verification_complete"). Credits are not charged for input errors, account issues, bank limitations, or temporary failures.

Network quick-reference

Result — structuredContent

typescript
{
  errorCategory: "input_validation" | "account_action_required" | "bank_limitation" | "verification_complete" | "transient_error",
  verificationOutcome: "match" | "partial_match" | "no_match" | null,
  errorCode: string | null,
  resolvedName: string | null,   // partial_match only — always null for CNY
  message: string,               // user-facing, safe to display directly
   creditCharged: boolean,        // true when a completed check deducted a credit
   creditsRemaining: number | null,
   network: string | null,        // unsupported input can be returned unchanged
   referenceId?: string           // only on unexpected TEMPORARILY_UNAVAILABLE failures
}

Example responses

json
{
  "errorCategory": "verification_complete",
  "verificationOutcome": "match",
  "errorCode": null,
  "resolvedName": null,
   "message": "Verification complete — the name matches the account holder. ✓ One credit was used.",
  "creditCharged": true,
  "creditsRemaining": 147,
  "network": "EUR"
}

Error codes

The following codes are returned as structured results, not isError: true. A completed verification has errorCode: null.

For an invalid network the message is “Please choose a supported network: EUR, GBP, INR, IDR, KRW, VND or CNY. No credit was used.” For insufficient credits it is “Your Vopify account doesn't have enough credits for this check. Add credits at vopify.io/billing and try again. No credit was used.” Other results include a user-facing message.

list_verifications

Returns the authenticated user's recent verification history, most recent first. Results are scoped to the authenticated account — you cannot retrieve another user's history.

typescript
{
  rows: Array<{
     created_at: string | null,   // ISO 8601 timestamp
     network: string | null,      // payment network
     iban_suffix: string | null,  // last 4 characters of account identifier
     provided_name: string | null,
    result_status: "FULL_MATCH" | "PARTIAL_MATCH" | "NO_MATCH" | "UNAVAILABLE",
     suggested_name: string | null
  }>
}

json
{
  "rows": [
    {
      "created_at": "2025-07-10T14:32:00Z",
       "network": "EUR",
      "iban_suffix": "4300",
      "provided_name": "Sample Payee",
      "result_status": "FULL_MATCH",
      "suggested_name": null
    },
    {
      "created_at": "2025-07-10T13:11:00Z",
       "network": "EUR",
      "iban_suffix": "7890",
      "provided_name": "Sample-Payee",
      "result_status": "PARTIAL_MATCH",
      "suggested_name": "Sample Payee"
    }
  ]
}

Error responses (isError: true)

• Expired session — reconnect Vopify in your assistant
• History query failure — “Your verification history couldn't be loaded right now. Please try again in a moment.” Internal details are logged, not returned.

account_status

Returns the authenticated user's credit balance and active plan. Takes no parameters — pass an empty object {}.

Parameters: None.

typescript
{
  email: string | null,
  credits: number,
   plan: "Starter" | "Growth" | "Scale" | "Pay-as-you-go" | "Subscription",
   subscription: null | {
     status: "active" | "trialing" | "past_due",
     renewsAt: string | null,
     cancelAtPeriodEnd: boolean
   }
}

The most recent live subscription is preferred, otherwise the most recent eligible subscription. A recognized subscription maps to Starter, Growth or Scale; an unrecognized subscription is labeled Subscription. Without an active, trialing or past-due subscription, the plan is Pay-as-you-go and subscription is null.

json
{
   "email": "sample@example.com",
   "credits": 1348,
   "plan": "Growth",
   "subscription": {
     "status": "active",
     "renewsAt": "2026-11-03T00:00:00Z",
     "cancelAtPeriodEnd": false
   }
}

Error responses (isError: true)

• Expired session — reconnect Vopify in your assistant
• Account or subscription query failure — “Your account status couldn't be loaded right now. Please try again in a moment.”

Connecting Vopify MCP

Error handling

verify_payee returns structured results for invalid input, expired sessions, suspended accounts, insufficient credits, bank limitations and temporary errors; it does not set isError: true in its handler. Use errorCategory and errorCode for these outcomes. list_verifications and account_status return isError: true with safe plain text on expired sessions or query failures. Protocol, authentication or schema rejections can also occur before a tool handler returns a structured result. Always check isError when present, then inspect structuredContent.

javascript
const result = await mcpClient.callTool("verify_payee", params);

if (result.isError) {
   // Tool-level or protocol failure — re-authenticate or retry
  console.error(result.content[0].text);
  return;
}

const data = result.structuredContent;

switch (data.errorCategory) {
  case "verification_complete":
    // 1 credit charged — process the result
    console.log(data.verificationOutcome); // "match" | "partial_match" | "no_match"
    console.log(data.resolvedName);        // suggested name for partial_match
    break;
  case "input_validation":
    // No credit charged — fix the inputs
    console.log(data.message);
    break;
  case "bank_limitation":
    // No credit charged — bank doesn't support verification
    console.log(data.message);
    break;
  case "transient_error":
    // No credit charged — retry after a delay
    break;
  case "account_action_required":
    // No credit charged — reconnect, top up credits, or contact support
    console.log(data.message);
    break;
}

Credits and billing

• 1 credit is deducted on a completed verify_payee check; check creditCharged for confirmation
• While a check runs, 1 credit is held on your balance. It is kept only if the check completes and returned automatically otherwise. Held-and-returned credits don't appear in your transaction history.
• No credit is charged for input_validation, account_action_required, bank_limitation, or transient_error outcomes
• creditCharged: true in the response confirms a credit was consumed
• creditsRemaining shows your balance when available; it can be null if it could not be read
• If your balance is too low, verify_payee returns errorCategory: "account_action_required" with an insufficient credits message — no credit consumed
• Check your balance anytime using account_status or at vopify.io/billing

Changelog

October 3, 2026. Changed:

• Expired session, suspended account, insufficient credits — Before: errorCategory: "input_validation" with codes SESSION_EXPIRED, ACCOUNT_SUSPENDED, INSUFFICIENT_CREDITS; structured result, isError not set. Now: errorCategory: "account_action_required", same codes, new reconnect / support / billing messages; structured result, isError not set.
• Unsupported network value — Before: rejected by the connector's input schema before reaching Vopify; no errorCategory or errorCode; may previously have returned a tool error (isError: true). Now: errorCategory: "input_validation", errorCode: "INVALID_FIELD" with the supported-network message; structured result, isError not set.
• Missing required field — Before: generic validation error. Now: errorCategory: "input_validation", errorCode: "MISSING_REQUIRED_FIELD" naming the field; structured result, isError not set.
• Unexpected failures — Before: the raw error was surfaced as a tool error (isError: true) with no category or code. Now: errorCategory: "transient_error", errorCode: "TEMPORARILY_UNAVAILABLE" with a referenceId for support; structured result, isError not set.
• Check order — Now: input validation, then session, then suspension, then credits, so input problems are reported before account problems.
• account_status — Before: no plan field. Now: returns plan and a subscription object.
• list_verifications — Before: no network field. Now: each item includes network.

Need help?

For integration support, email operations@vopify.io with subject line MCP Integration Support. Include your client platform (n8n, Claude, ChatGPT, or custom), the tool you're calling, the parameters you're sending (redact any real IBANs or account numbers), and the full response you're receiving.