Portugal Payments (Stripe — Multibanco)

Official6 toolsLive

by junter1989k-ai · JavaScript

Portugal payments for AI agents — Multibanco via Stripe. Never holds funds.

Topics

ai-agentclaudee-invoiceinvoicemcpmcp-serverpaymentsportugalstripetaxvatwishpool

Captured live from the server via tools/list.

create_payment_link

Create a payment link in EUR for Portugal via Stripe (Checkout Sessions). Buyer pays with Multibanco (the rail Portuguese buyers actually use), cards, Apple Pay. Returns a hosted checkout URL the buyer opens to pay — payment completes automatically, no confirm step. Bring your own credentials via HTTP header (x-stripe-secret-key; free test credentials from dashboard.stripe.com never move real money). Money always flows buyer→Stripe→merchant; this service never touches funds. Optional: issue_invoice=true auto-creates a VAT-ready invoice (PDF + hosted page, emailed to the buyer) after payment; collect_tax_id=true collects the buyer's business tax ID (e.g. EU VAT number) at checkout and puts it on the invoice.

Parameters6

amount_eur	number	required	Amount in EUR (decimals allowed), e.g. 5.0. Minimum 0.5.
description	string	required	What this payment is for (shown to the buyer, ≤200 chars)
customer_email	string	optional	Optional buyer email.
success_url	string	optional	Optional https URL to send the buyer to after payment.
issue_invoice	boolean	optional	true = Stripe automatically creates and emails a post-payment invoice (PDF + hosted invoice page). Ideal for B2B / VAT bookkeeping. Note: Stripe charges a small Invoicing fee per invoice issued.
collect_tax_id	boolean	optional	true = ask the buyer for their business tax ID (e.g. EU VAT number) on the checkout page; it appears on the invoice. Combine with issue_invoice for a VAT-compliant receipt.

Raw schema

{
  "type": "object",
  "properties": {
    "amount_eur": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 1000000,
      "description": "Amount in EUR (decimals allowed), e.g. 5.0. Minimum 0.5."
    },
    "description": {
      "type": "string",
      "description": "What this payment is for (shown to the buyer, ≤200 chars)"
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email."
    },
    "success_url": {
      "type": "string",
      "description": "Optional https URL to send the buyer to after payment."
    },
    "issue_invoice": {
      "type": "boolean",
      "description": "true = Stripe automatically creates and emails a post-payment invoice (PDF + hosted invoice page). Ideal for B2B / VAT bookkeeping. Note: Stripe charges a small Invoicing fee per invoice issued."
    },
    "collect_tax_id": {
      "type": "boolean",
      "description": "true = ask the buyer for their business tax ID (e.g. EU VAT number) on the checkout page; it appears on the invoice. Combine with issue_invoice for a VAT-compliant receipt."
    }
  },
  "required": [
    "amount_eur",
    "description"
  ]
}

query_payment_status

Check whether a Portugal payment (created by create_payment_link) has been paid. Queries Stripe directly — pull-based, no webhook needed. paid=true when status is PAID. If the payment was created with issue_invoice=true, the result also includes invoice_url and invoice_pdf once paid.

Parameters1

session_id

string

required

The session_id returned by create_payment_link

Raw schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "The session_id returned by create_payment_link"
    }
  },
  "required": [
    "session_id"
  ]
}

refund_payment

Refund a paid payment (created by create_payment_link). Full refund by default; pass amount for a partial refund where supported. Refunds respect the same owner policy guardrails (x-agentpay-max-amount) as payments — the amount is checked before anything is sent to the gateway.

Parameters2

session_id	string	required	The session_id of the paid payment (same id used by query_payment_status)
amount	number	optional	Optional partial-refund amount in the local currency major unit. Omit for a full refund.

Raw schema

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "The session_id of the paid payment (same id used by query_payment_status)"
    },
    "amount": {
      "type": "number",
      "description": "Optional partial-refund amount in the local currency major unit. Omit for a full refund."
    }
  },
  "required": [
    "session_id"
  ]
}

create_subscription_link

Create a recurring subscription checkout link (monthly/yearly/weekly billing) via Stripe. The buyer opens the URL, enters their card once, and is then charged automatically every period until canceled. Amount is per billing period in the local currency major unit. Respects the same owner policy guardrails as payments (the per-period amount is checked before anything is created).

Parameters5

amount_eur	number	required	Amount charged per billing period (local currency major unit)
interval	string	optional	Billing period. Default "month".
description	string	required	What the subscription is for (shown to the buyer, <=200 chars)
customer_email	string	optional	Optional buyer email (pre-filled at checkout; receipt goes there).
success_url	string	optional	Optional https URL to send the buyer to after subscribing.

Raw schema

{
  "type": "object",
  "properties": {
    "amount_eur": {
      "type": "number",
      "description": "Amount charged per billing period (local currency major unit)"
    },
    "interval": {
      "type": "string",
      "enum": [
        "month",
        "year",
        "week",
        "day"
      ],
      "description": "Billing period. Default \"month\"."
    },
    "description": {
      "type": "string",
      "description": "What the subscription is for (shown to the buyer, <=200 chars)"
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email (pre-filled at checkout; receipt goes there)."
    },
    "success_url": {
      "type": "string",
      "description": "Optional https URL to send the buyer to after subscribing."
    }
  },
  "required": [
    "amount_eur",
    "description"
  ]
}

query_subscription

Check a subscription created by create_subscription_link. Accepts the session_id (cs_...) or subscription_id (sub_...). active=true when the subscription is ACTIVE or TRIALING; NOT_SUBSCRIBED_YET means the buyer has not completed checkout.

Parameters1

string

required

session_id (cs_...) returned by create_subscription_link, or subscription_id (sub_...)

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "session_id (cs_...) returned by create_subscription_link, or subscription_id (sub_...)"
    }
  },
  "required": [
    "id"
  ]
}

cancel_subscription

Cancel a subscription. By default the subscription stays active until the end of the current paid period (fair to the buyer); pass immediate=true to cancel right now.

Parameters2

id	string	required	session_id (cs_...) or subscription_id (sub_...)
immediate	boolean	optional	true = cancel immediately. Default false = cancel at period end.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "session_id (cs_...) or subscription_id (sub_...)"
    },
    "immediate": {
      "type": "boolean",
      "description": "true = cancel immediately. Default false = cancel at period end."
    }
  },
  "required": [
    "id"
  ]
}

README.md3 KBView on GitHub

Portugal Payments MCP — let AI agents accept payments in Portugal

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "portugal-payments": {
      "type": "http",
      "url": "https://mcp-pt.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/portugal-payments-mcp && cd portugal-payments-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Live · MCP endpoint: https://mcp-pt.wishpool.app/mcp · Listed on the official MCP Registry as app.wishpool/portugal-payments-mcp · Part of a 50-country family — hub: mcp.wishpool.app

A remote MCP server that lets any AI agent (Claude, ChatGPT, Cursor…) accept payments in Portugal: Multibanco (the rail Portuguese buyers actually use), cards, Apple Pay — via Stripe's hosted checkout.

⚖️ Stateless translation layer: funds always flow buyer → Stripe → merchant directly. Never holds funds or stores credentials — no database at all.

Quick start

MCP endpoint: https://mcp-pt.wishpool.app/mcp (Streamable HTTP, stateless JSON-RPC)

Header	Value
`x-stripe-secret-key`	your Stripe secret key (sk_test_ = test mode from dashboard.stripe.com, sk_live_ = production)

Tools

Tool	What it does
`create_payment_link`	Create a EUR hosted-checkout link.
`query_payment_status`	Pull-based status check; `paid=true` when PAID. Returns `invoice_url` + `invoice_pdf` once paid for invoiced payments.
`issue_invoice` / `collect_tax_id` (options on create)	VAT-ready invoicing: auto-create a Stripe invoice (PDF, emailed to the buyer) and collect the buyer's EU VAT / business tax ID at checkout.
`refund_payment`	Full or partial refund of a paid payment; respects the same owner policy guardrails.
`create_subscription_link` / `query_subscription` / `cancel_subscription`	Recurring billing: the buyer authorizes once and is charged every period until canceled.

Develop

bash

node test/serve.js      # local server (http://localhost:3243/mcp)
node test/e2e.js        # protocol + validation suite (probes real Stripe auth errors)

Zero runtime dependencies; Node ≥ 18. MIT license.

Install

Tools (6)

create_payment_linkquery_payment_statusrefund_paymentcreate_subscription_linkquery_subscriptioncancel_subscription

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp-pt.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "portugal-payments-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-pt.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.