使用说明

Payment Verification MCP

A Model Context Protocol (MCP) server that lets AI agents verify payment status across multiple Portuguese and European gateways — IFTHENPAY (Multibanco, MB WAY, PAYSHOP) and Klarna — from a single interface.

The Problem

AI agents and automation workflows often need to answer a simple question: "Has this payment been made?"

The answer is scattered across multiple gateways, each with its own API, auth model, and response format. A support agent, an n8n workflow, or a Claude-powered assistant shouldn't need to know the difference between an IFTHENPAY Multibanco reference and a Klarna order ID.

The Solution

A single MCP server that normalises payment verification across gateways. Ask "is order #12345 paid?" — the agent picks the right tool and returns a plain-language answer.

Capabilities

8 tools across 2 gateway families — built from real integrations with Portuguese and European payment infrastructure:

Gateway	Tools	Payment methods
IFTHENPAY	4	Multibanco, MB WAY, PAYSHOP, Credit Card, Cofidis
Klarna	4	BNPL, Card — captures, refunds, sessions

What this replaces:

Custom integration code per gateway per use case
Manual dashboard lookups to answer "is this paid?"
Webhook validation logic duplicated across projects

Reference implementation — patterns extracted from production payment integrations (e-commerce and ERP). Client credentials and business logic omitted; integration available on request.

Architecture

flowchart LR
    A[AI Agent\nClaude / n8n / Custom] -->|MCP tool call| B[payment-verification-mcp]

    B --> C[IFTHENPAY Module]
    B --> D[Klarna Module]

    C -->|backoffice API| E[IFTHENPAY\nMB / MBWAY / PAYSHOP / CCARD]
    D -->|order management API| F[Klarna\nBNPL / Card]

    E --> C --> B
    F --> D --> B

    B -->|structured result + summary| A

Tools

IFTHENPAY (4 tools)

Tool	Description
`ifthenpay_check_payment`	Check if a specific reference has been paid. Returns amount, date, and plain-language summary
`ifthenpay_check_by_order`	Check payment by order ID (used when creating the reference)
`ifthenpay_list_payments`	List payments in a date range, filtered by entity, reference, or order ID
`ifthenpay_validate_callback`	Validate a webhook/callback payload using the anti-phishing key

IFTHENPAY entities supported: MB (Multibanco), MBWAY, PAYSHOP, CCARD, COFIDIS

Klarna (4 tools)

Tool	Description
`klarna_get_order`	Get order status, fraud status, amounts, and order lines
`klarna_get_capture`	Get details of a specific capture within an order
`klarna_list_captures`	List all captures for an order with totals
`klarna_get_session`	Get payment session status and available methods

Stack

Component	Tool
Protocol	Model Context Protocol SDK
Language	TypeScript 5 + Node.js
Schema validation	Zod
Gateways	IFTHENPAY API, Klarna Order Management API

Setup

Prerequisites

Node.js 18+
IFTHENPAY backoffice credentials (anti-phishing key + entity keys)
Klarna API credentials (username + password, production or playground)

1. Install

git clone https://github.com/RobsonAdvincula/payment-verification-mcp.git
cd payment-verification-mcp
npm install
npm run build

2. Configure environment

# IFTHENPAY
IFTHENPAY_BACKOFFICE_KEY=your_backoffice_key
IFTHENPAY_ANTI_PHISHING_KEY=your_anti_phishing_key
IFTHENPAY_MB_KEY=your_mb_entity_key
IFTHENPAY_MBWAY_KEY=your_mbway_key

# KLARNA
KLARNA_USERNAME=your_api_username
KLARNA_PASSWORD=your_api_password
KLARNA_REGION=eu          # eu | na | oc
KLARNA_ENVIRONMENT=production   # production | playground

3. Add to MCP host

{
  "mcpServers": {
    "payment-verification": {
      "command": "node",
      "args": ["/path/to/payment-verification-mcp/dist/index.js"],
      "env": {
        "IFTHENPAY_BACKOFFICE_KEY": "...",
        "KLARNA_USERNAME": "...",
        "KLARNA_PASSWORD": "..."
      }
    }
  }
}

Example Interactions

Support agent checking a Multibanco reference:

User: "Customer says they paid reference 123 456 789 but order is still pending"

→ ifthenpay_check_payment({ reference: "123456789", entity: "MB" })
← {
    isPaid: true,
    amount: "49.99",
    paidAt: "2026-03-20T14:32:00",
    summary: "Payment confirmed — 49.99 EUR on 2026-03-20 at 14:32."
  }

Agent: "The payment was confirmed at 14:32 today. The order status may be delayed — I'll trigger a manual sync."

Validating a webhook before processing:

→ ifthenpay_validate_callback({ entity: "MB", reference: "...", ... })
← { valid: true, summary: "Callback is AUTHENTIC." }

License

MIT — free to use, adapt, and build on.

Built by Robson Advincula — AI & Automation Consultant