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