ifthenpay MCP — Payments

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.

Endpoint

The MCP server accepts exclusively POST requests:

POST https://ai.ifthenpay.com/mcp/payments/

Required header:

Content-Type: application/json

CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: POST, OPTIONS

OPTIONS preflight requests receive an immediate HTTP 200 response.

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 — 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 */ }
  }
}

Success response

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

multibanco_create_reference POST

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

Input

Output (content[0].text — JSON)

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

Output

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

Output

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

Output

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.

Input

Output

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

Method prefixes for the accounts field

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

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.

Input

Output

pix_create_payment POST

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

Input

Output

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

Output

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

JSON-RPC errors

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
  }
}