AI导哈

SIBS支付网关MCP服务

一个将SIBS支付网关封装为MCP工具的服务器，使AI代理能够在Claude Desktop、n8n等MCP兼容环境中创建结账、查询支付状态、执行捕获/退款/取消操作，并生成Multibanco和MB WAY支付通知。

  • by RobsonAdvincula
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 RobsonAdvincula/sibs-payment-mcp

使用说明

SIBS Payment MCP

A Model Context Protocol (MCP) server that exposes the SIBS payment gateway as tools for AI agents — enabling LLMs to create checkouts, verify payments, issue refunds, and generate Multibanco references natively in any MCP-compatible environment.

What It Does

Bridges the SIBS payment gateway to the MCP ecosystem. Any AI agent or LLM-powered tool running in an MCP-compatible host (Claude Desktop, n8n, custom agents) can:

  • Check payment status in real time
  • Create checkout sessions with configurable payment methods
  • Capture, refund, or cancel authorised payments
  • Generate Multibanco references for ATM/homebanking payment
  • Initiate MB WAY push notifications to a customer's phone

Architecture

flowchart LR
    A[AI Agent\nClaude / n8n] -->|MCP tool call| B[sibs-payment-mcp\nMCP Server]
    B -->|REST API| C[SIBS Gateway\nAPI]
    C -->|response| B
    B -->|structured result| A

    subgraph Tools
        T1[sibs_create_checkout]
        T2[sibs_payment_status]
        T3[sibs_capture_payment]
        T4[sibs_refund_payment]
        T5[sibs_cancel_payment]
        T6[sibs_generate_mb_reference]
        T7[sibs_mbway_payment]
        T8[sibs_test]
    end

Tools (8 total)

Tool Description
sibs_create_checkout Create a new checkout. Returns transactionID and hosted checkout URL
sibs_payment_status Get payment state, amount, method, and timestamps by transaction ID
sibs_capture_payment Capture an authorised payment — full or partial
sibs_refund_payment Refund a captured payment — full or partial
sibs_cancel_payment Cancel an authorised payment before capture
sibs_generate_mb_reference Generate a Multibanco entity/reference for ATM payment
sibs_mbway_payment Send MB WAY push to customer phone (351#912345678 format)
sibs_test Validate credentials and connectivity

Stack

Component Tool
Protocol Model Context Protocol SDK
Language TypeScript 5 + Node.js
Schema validation Zod
Payment gateway SIBS API (Portugal)
Build tsc → dist/

Setup

Prerequisites

  • Node.js 18+
  • SIBS merchant account with API credentials
  • MCP-compatible host (Claude Desktop, n8n, custom agent)

1. Install

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

2. Configure environment

SIBS_BASE_URL=https://stargate.sibs.pt/m001/v1
SIBS_BEARER_TOKEN=your_bearer_token
SIBS_CLIENT_ID=your_client_id
SIBS_TERMINAL_ID=your_terminal_id

3. Add to MCP host

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sibs-payment": {
      "command": "node",
      "args": ["/path/to/sibs-payment-mcp/dist/index.js"],
      "env": {
        "SIBS_BEARER_TOKEN": "...",
        "SIBS_CLIENT_ID": "...",
        "SIBS_TERMINAL_ID": "..."
      }
    }
  }
}

n8n MCP Client node: point to the compiled dist/index.js with the same env vars.

Example Interactions

Create a payment and send MB WAY:

Agent: "Create a €29.99 checkout for customer +351912345678"

→ sibs_create_checkout({ amount: 2999, currency: "EUR", paymentMethods: ["MBWAY"] })
→ sibs_mbway_payment({ transactionId: "txn_xxx", amount: 2999, customerPhone: "351#912345678" })

Result: "MB WAY notification sent. Customer has 4 minutes to confirm."

Verify and refund:

Agent: "Check transaction txn_abc and refund if paid"

→ sibs_payment_status({ transactionId: "txn_abc" })
  ← { status: "Success", amount: 4999 }
→ sibs_refund_payment({ transactionId: "txn_abc" })
  ← { refunded: true }

Payment Methods Supported

  • CARD — Visa / Mastercard
  • MBWAY — MB WAY mobile payment
  • REFERENCE — Multibanco ATM reference
  • COFIDIS — Instalments
  • PAYPAL — PayPal

License

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

Built by Robson Advincula — AI & Automation Consultant

相关 MCP