ifthenpay Payments MCP

ifthenpay MCP — Payments

Technical documentation for the ifthenpay payments MCP server. Covers the communication protocol, all available methods, each tool's schema, and request/response examples.

Overview

The ifthenpay MCP ( Model Context Protocol ) server exposes ifthenpay payment APIs as invocable tools for AI agents. It implements the JSON-RPC 2.0 protocol and MCP specification version 2025-03-26.

The server is identified as ifthenpay-mcp v1.0.0 and registers 9 tools covering all ifthenpay payment methods: Multibanco, MB WAY, Payshop, Credit Card, PinPay (Pay by Link), Cofidis Pay, PIX, and payment lookup.

Component Detail Protocol JSON-RPC 2.0 — Streamable HTTP (POST) + SSE (GET) MCP version 2025-03-26 Server name ifthenpay-mcp Server version 1.0.0

Endpoint

https://ai.ifthenpay.com/mcp/payments/index.php

Two transports are supported simultaneously:

Method Transport Use case POST Streamable HTTP (JSON-RPC) Direct API calls, agents, MCP clients GET SSE stream Claude desktop and other MCP hosts via url config

POST — Streamable HTTP

Send JSON-RPC 2.0 messages directly. Required header:

Content-Type: application/json

Notifications (messages without id) return HTTP 202 with no body. All other requests return HTTP 200 with a JSON body.

GET — SSE transport

Opens a persistent text/event-stream connection. The server immediately sends an endpoint event with the POST URL, then keeps the stream alive with periodic pings:

event: endpoint
data: "https://ai.ifthenpay.com/mcp/payments/index.php"

: ping

Use this transport when connecting via Claude desktop or any MCP host that supports the url configuration option — no local software required.

Claude desktop configuration

Add the following to claude_desktop_config.json (located at %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS):

{
 "mcpServers": {
 "ifthenpay": {
 "url": "https://ai.ifthenpay.com/mcp/payments/index.php"
 }
 }
}

CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization, Mcp-Session-Id
Access-Control-Allow-Methods: GET, POST, OPTIONS

OPTIONS preflight requests receive an immediate HTTP 200 response.

Client Integrations

Any MCP-compatible client can connect using the SSE endpoint. Below are ready-to-use configurations for the most common tools. If authentication is enabled, add "headers": {"Authorization": "Bearer <token>"} to each entry.

Claude Desktop

File: %APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Cursor

Global: ~/.cursor/mcp.json · Per project: .cursor/mcp.json

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

{
 "mcpServers": {
 "ifthenpay": {
 "serverUrl": "https://ai.ifthenpay.com/mcp/payments/index.php"
 }
 }
}

VS Code — GitHub Copilot

File: .vscode/mcp.json (per project) or via User Settings → MCP .

{
 "servers": {
 "ifthenpay": {
 "type": "sse",
 "url": "https://ai.ifthenpay.com/mcp/payments/index.php"
 }
 }
}

ChatGPT Desktop

File: %APPDATA%\ChatGPT\claude_desktop_config.json (Windows) · ~/Library/Application Support/ChatGPT/claude_desktop_config.json (macOS). Requires ChatGPT desktop app with MCP support enabled.

Continue.dev

File: ~/.continue/config.json (global) · .continue/config.json (per project)

{
 "mcpServers": [
 {
 "name": "ifthenpay",
 "transport": {
 "type": "sse",
 "url": "https://ai.ifthenpay.com/mcp/payments/index.php"
 }
 }
 ]
}

Zed

File: ~/.config/zed/settings.json — add to the context_servers key.

{
 "context_servers": {
 "ifthenpay": {
 "command": {
 "path": "php",
 "args": ["/path/to/mcp/stdio-bridge.php"]
 }
 }
 }
}

Zed currently supports stdio transport only. Download stdio-bridge.php and update the path accordingly.

Gemini (Google AI Studio)

In Google AI Studio, go to Settings → Tools → Add MCP Server and enter the endpoint URL directly:

Native MCP support in Gemini products is evolving — refer to the Google AI documentation for the latest configuration steps.

JSON-RPC 2.0 Protocol

Request format

{
 "jsonrpc": "2.0",
 "id": 1,
 "method": " ",
 "params": { /* method-specific parameters */ }
}

Success response

{
 "jsonrpc": "2.0",
 "id": 1,
 "result": { /* result */ }
}

Error response

{
 "jsonrpc": "2.0",
 "id": 1,
 "error": { "code": -32600, "message": "error description" }
}

Available methods

Method Description initialize Initial handshake — returns protocol version and capabilities ping Health check — returns an empty object tools/list Lists all registered tools with their schemas tools/call Executes a tool with the provided arguments

Method — initialize

Mandatory handshake to establish the MCP session. Must be the first request.

Request

{
 "jsonrpc": "2.0", "id": 1, "method": "initialize",
 "params": {
 "protocolVersion": "2025-03-26",
 "clientInfo": { "name": "my-client", "version": "1.0.0" }
 }
}

Response

{
 "jsonrpc": "2.0", "id": 1,
 "result": {
 "protocolVersion": "2025-03-26",
 "serverInfo": { "name": "ifthenpay-mcp", "version": "1.0.0" },
 "capabilities": { "tools": {} }
 }
}

Method — ping

Checks that the server is reachable. No parameters required.

// Request
{ "jsonrpc": "2.0", "id": 2, "method": "ping" }

// Response
{ "jsonrpc": "2.0", "id": 2, "result": {} }

Method — tools/list

Returns all registered tools with their name, description, and input schema (JSON Schema Draft 7).

// Request
{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }

// Response (abbreviated)
{
 "jsonrpc": "2.0", "id": 3,
 "result": {
 "tools": [
 {
 "name": "multibanco_create_reference",
 "description": "Creates a Multibanco payment reference...",
 "inputSchema": { "type": "object", "properties": { /* ... */ } }
 }
 // ... + 8 more tools
 ]
 }
}

Method — tools/call

Executes a tool. The name field identifies the tool; arguments contains the parameters according to the schema.

// Request
{
 "jsonrpc": "2.0", "id": 4, "method": "tools/call",
 "params": {
 "name": " ",
 "arguments": { /* tool parameters */ }
 }
}

{
 "jsonrpc": "2.0", "id": 4,
 "result": {
 "content": [{ "type": "text", "text": "{\"entity\":\"11249\",\"reference\":\"123456789\",...}" }],
 "isError": false
 }
}

content[0].text contains a JSON string with the data returned by the ifthenpay API. When isError is true, text contains the error message.

multibanco_create_reference POST

Creates a Multibanco payment reference for payment at any Portuguese ATM or online banking.

Input

Field Type Req. Description mb_key string Required ifthenpay Multibanco key order_id string Required Unique order identifier amount number Required Amount in EUR (e.g. 10.50) expiry_days integer Optional Days until the reference expires; omit for no expiry

Output (content[0].text — JSON)

Field Type Description entity string Multibanco entity (5 digits) reference string Payment reference (9 digits) amount string Payment amount expiry_date string|null Expiry date (YYYYMMDD) or null request_id string Unique request identifier

Example

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "multibanco_create_reference",
 "arguments": { "mb_key": "{mb_key}", "order_id": "1001", "amount": 25.00 }
 }
}

// Response
{
 "result": {
 "content": [{ "type": "text", "text": "{\"entity\":\"11249\",\"reference\":\"123456789\",\"amount\":\"25.00\",\"expiry_date\":null,\"request_id\":\"req_abc123\"}" }],
 "isError": false
 }
}

mbway_request_payment POST

Sends a payment request to the customer's phone via the MB WAY app. The customer has 4 minutes to approve.

Input

Field Type Req. Description mbway_key string Required ifthenpay MB WAY key order_id string Required Unique order identifier amount number Required Amount in EUR (e.g. 10.50) phone string Required Phone number in format 351#912345678 (country code#number) description string Optional Description shown in the MB WAY app

Output

Field Type Description request_id string Token for status polling via mbway_check_status status string Initial status — always "pending" message string Status message

Example

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "mbway_request_payment",
 "arguments": { "mbway_key": "{mbway_key}", "order_id": "912345678", "amount": 15.50, "phone": "351#912345678" }
 }
}

// Response
{
 "result": {
 "content": [{ "type": "text", "text": "{\"request_id\":\"mbw_7f3a1b2c\",\"status\":\"pending\",\"message\":\"Payment request sent\"}" }],
 "isError": false
 }
}

mbway_check_status GET

Checks the status of an MB WAY payment request. Use the request_id returned by mbway_request_payment.

Input

Field Type Req. Description mbway_key string Required ifthenpay MB WAY key request_id string Required Request ID returned by the payment request

Output

Field Type Description status string paid | rejected expired declined pending unknown status_code string Raw API code: 000=paid, 020=rejected, 101=expired, 122=cancelled message string Status message created_at string|null Creation timestamp updated_at string|null Last update timestamp

Example

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "mbway_check_status",
 "arguments": { "mbway_key": "{mbway_key}", "request_id": "mbw_7f3a1b2c" }
 }
}

// Response — approved
{
 "result": {
 "content": [{ "type": "text", "text": "{\"status\":\"paid\",\"status_code\":\"000\",\"message\":\"Payment approved\",\"created_at\":\"2026-06-18 10:00:00\",\"updated_at\":\"2026-06-18 10:02:34\"}" }],
 "isError": false
 }
}

payshop_create_reference POST

Generates a Payshop reference for cash payment at over 5,000 agents, CTT post offices, and convenience stores in Portugal.

Input

Field Type Req. Description payshop_key string Required ifthenpay Payshop key order_id string Required Unique order identifier (max 25 chars) amount number Required Amount in EUR (e.g. 10.50) expiry_date string Optional Expiry date in YYYYMMDD format; omit for no expiry

Output

Field Type Description reference string Payshop reference (13 digits) request_id string Unique request identifier amount string Payment amount

Example

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "payshop_create_reference",
 "arguments": { "payshop_key": "{payshop_key}", "order_id": "2024001", "amount": 50.00 }
 }
}

// Response
{
 "result": {
 "content": [{ "type": "text", "text": "{\"reference\":\"1234567890123\",\"request_id\":\"ps_req456\",\"amount\":\"50.00\"}" }],
 "isError": false
 }
}

creditcard_create_payment POST

Creates a hosted credit/debit card payment session. Supports Visa and Mastercard.

When invoked through the AI agent, this method is redirected to pinpay_create_payment with selected_method="4". Direct invocation via MCP retains the original behaviour.

Input

Field Type Req. Description ccard_key string Required ifthenpay Credit Card key order_id string Required Unique order identifier (max 15 chars) amount number Required Amount in EUR success_url string Required URL after successful payment error_url string Required URL on payment failure cancel_url string Required URL if the customer cancels language string Optional Checkout language: "pt" or "en"; default: "pt"

Output

Field Type Description payment_url string Hosted checkout URL request_id string Unique request identifier amount string Payment amount

pinpay_create_payment POST

Creates a PinPay (Pay by Link) payment link supporting multiple payment methods. Returns a URL and a PIN code for the customer to access the checkout.

Input

Field Type Req. Description gateway_key string Required ifthenpay Gateway key order_id string Required Unique order identifier (max 15 chars) amount number Required Amount (EUR or BRL for PIX) accounts string Optional Semicolon-separated methods in METHOD|KEY format — see table below selected_method string Optional Pre-selects a method: 1=MB, 2=MBWAY, 3=Payshop, 4=Card, 7=Cofidis, 8=PIX. Omit when multiple methods. otp string Optional Single-use payment: "true" — link expires after one use expiry_date string Optional Link expiry date in YYYYMMDD format description string Optional Description on the payment page (max 200 chars) lang string Optional Language: "pt", "en", "es", "fr" success_url string Optional URL after successful payment error_url string Optional URL on payment failure cancel_url string Optional URL if the customer cancels btn_close_url string Optional URL for the close button on the payment page btn_close_label string Optional Label for the close button

Method prefixes for the accounts field

Method Prefix selected_method Multibanco MB|{mb_key} 1 MB WAY MBWAY|{mbway_key} 2 Payshop PAYSHOP|{payshop_key} 3 Credit Card CCARD|{ccard_key} 4 Cofidis Pay COFIDIS|{cofidis_key} 7 PIX PIX|{pix_key} 8 Google Pay GOOGLE|{google_key} 4 Apple Pay APPLE|{apple_key} 4

Example with all methods:

"MB|{mb_key};MBWAY|{mbway_key};PAYSHOP|{payshop_key};CCARD|{ccard_key};COFIDIS|{cofidis_key};PIX|{pix_key};GOOGLE|{google_key};APPLE|{apple_key}"

Output

Field Type Description redirect_url string Payment URL to share with the customer pinpay_url string|null Direct pinpay.pt URL pin_code string|null PIN code to access the checkout amount string Payment amount

Example — single-use credit card link

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "pinpay_create_payment",
 "arguments": {
 "gateway_key": "{gateway_key}", "order_id": "CC-001", "amount": 99.99,
 "accounts": "CCARD|{ccard_key}", "selected_method": "4", "otp": "true"
 }
 }
}

// Response
{
 "result": {
 "content": [{ "type": "text", "text": "{\"redirect_url\":\"https://pinpay.pt/pay/a1b2c3\",\"pin_code\":\"123456\",\"amount\":\"99.99\"}" }],
 "isError": false
 }
}

cofidis_create_payment POST

Creates a Cofidis Pay instalment payment. Available mainly in Portugal and Spain.

When invoked through the AI agent, this method is redirected to pinpay_create_payment with accounts="COFIDIS|{cofidis_key}" and selected_method="7".

Input

Field Type Req. Description cofidis_key string Required ifthenpay Cofidis Pay key order_id string Required Unique order identifier (max 15 chars) amount number Required Amount in EUR (subject to Cofidis limits) return_url string Required Return URL; the API appends &Success=True on approval description string Optional Payment description or reference customer_name string Optional Customer full name customer_email string Optional Customer email customer_phone string Optional Phone with country code (e.g. +351256245560)

Output

Field Type Description payment_url string Cofidis checkout URL request_id string Unique request identifier amount string Payment amount

pix_create_payment POST

Creates a PIX payment for Brazilian customers. Requires the customer's CPF.

When invoked through the AI agent, this method is redirected to pinpay_create_payment with accounts="PIX|{pix_key}" and selected_method="8".

Input

Field Type Req. Description pix_key string Required ifthenpay PIX key order_id string Required Unique order identifier (max 25 chars) amount number Required Amount in BRL (e.g. 50.00) redirect_url string Required Return URL after payment customer_name string Required Customer full name (max 150 chars) customer_cpf string Required CPF — digits only (e.g. 74026594025) customer_email string Required Customer email customer_phone string Required Phone with country code (e.g. +5585912345678) description string Optional Description (max 200 chars) customer_address string Optional Address customer_city string Optional City customer_state string Optional State (e.g. CE, SP) customer_zip_code string Optional Postal code

Output

Field Type Description request_id string Unique request identifier payment_url string Payment URL qr_code_value string|null PIX QR code value amount string Payment amount

payments_list POST

Lists completed payments via Backoffice Key. Supports filtering by method, dates, order ID, reference, or request ID. Returns up to 1,000 records without filters.

Input

Field Type Req. Description bo_key string Required ifthenpay Backoffice key (provided in your contract) entity string Optional Method filter: MB, MBWAY, PAYSHOP, CCARD, COFIDIS, GOOGLE, APPLE, PIX, or entity number (5 digits). Omit for all. sub_entity string Optional Method key or sub-entity order_id string Optional Filter by order ID reference string Optional Filter by reference request_id string Optional Filter by request ID amount string Optional Filter by exact amount date_start string Optional Start date: dd-MM-yyyy HH:mm:ss date_end string Optional End date: dd-MM-yyyy HH:mm:ss

Output

Field Type Description count integer Number of records returned payments array List of payment objects

Example — MB payments from June 2026

// Request
{
 "jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {
 "name": "payments_list",
 "arguments": {
 "bo_key": "{bo_key}", "entity": "MB",
 "date_start": "01-06-2026 00:00:00", "date_end": "30-06-2026 23:59:59"
 }
 }
}

// Response
{
 "result": {
 "content": [{ "type": "text", "text": "{\"count\":2,\"payments\":[{\"order_id\":\"1001\",\"amount\":\"25.00\",\"status\":\"paid\"},{\"order_id\":\"1002\",\"amount\":\"80.00\",\"status\":\"paid\"}]}" }],
 "isError": false
 }
}

Errors

HTTP errors

HTTP Cause 405 HTTP method not allowed — only POST is accepted

JSON-RPC errors

Code Meaning -32700 Parse error — invalid JSON -32600 Invalid request — missing required fields -32601 Method not found — unknown method -32602 Invalid params — tool not found or invalid arguments -32603 Internal error — unexpected server error

Tool errors (isError: true)

When a tool fails, the response has isError: true and content[0].text contains the message:

{
 "result": {
 "content": [{ "type": "text", "text": "Invalid key or API error: ..." }],
 "isError": true
 }
}