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```mermaid
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```bash
git clone https://github.com/RobsonAdvincula/payment-verification-mcp.git
cd payment-verification-mcp
npm install
npm run build
2. Configure environment```env
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```json
{
"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
