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": "<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": "<tool_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
  }
}