MCP 服务器

SIBS Payment MCP

Enables AI agents to integrate the SIBS payment gateway, providing tools for creating checkouts, checking payment status, issuing refunds, and generating Multibanco references directly through natural language.

README

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 }