ifthenpay Payments MCP

ifthenpay MCP — Pagos

Documentación técnica para el servidor MCP de pagos ifthenpay.
Cubre el protocolo de comunicación, todos los métodos disponibles, el esquema de cada herramienta y ejemplos de solicitud/respuesta.

Descripción general

El servidor MCP (Model Context Protocol) de ifthenpay expone las API de pago de ifthenpay como herramientas invocables para agentes de IA. Implementa el protocolo JSON-RPC 2.0 y la especificación MCP versión 2025-03-26.

El servidor se identifica como ifthenpay-mcp v1.0.0 y registra 9 herramientas que cubren todos los métodos de pago de ifthenpay: Multibanco, MB WAY, Payshop, Tarjeta de Crédito, PinPay (Pago por Enlace), Cofidis Pay, PIX y consulta de pagos.

Componente	Detalle
Protocolo	JSON-RPC 2.0 — HTTP Streamable (POST) + SSE (GET)
Versión MCP	2025-03-26
Nombre servidor	ifthenpay-mcp
Versión servidor	1.0.0

Endpoint

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

Se admiten dos transportes simultáneamente:

Método	Transporte	Caso de uso
POST	HTTP Streamable (JSON-RPC)	Llamadas API directas, agentes, clientes MCP
GET	Flujo SSE	Claude desktop y otros hosts MCP mediante configuración de URL

POST — HTTP Streamable

Envíe mensajes JSON-RPC 2.0 directamente. Cabecera requerida:

Content-Type: application/json

Las notificaciones (mensajes sin id) devuelven HTTP 202 sin cuerpo. Todas las demás solicitudes devuelven HTTP 200 con un cuerpo JSON.

GET — Transporte SSE

Abre una conexión persistente text/event-stream. El servidor envía inmediatamente un evento endpoint con la URL POST y luego mantiene el flujo activo con pings periódicos:

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

: ping

Utilice este transporte al conectarse mediante Claude desktop o cualquier host MCP que admita la opción de configuración url — no se requiere software local.

Configuración de Claude desktop

Añada lo siguiente a claude_desktop_config.json (ubicado en %APPDATA%\Claude\ en Windows o ~/Library/Application Support/Claude/ en 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

Las solicitudes de verificación previa OPTIONS reciben una respuesta inmediata HTTP 200.

Integraciones de cliente

Cualquier cliente compatible con MCP puede conectarse mediante el endpoint SSE. A continuación se muestran configuraciones listas para usar de las herramientas más comunes. Si la autenticación está habilitada, añada "headers": {"Authorization": "Bearer <token>"} a cada entrada.

Claude Desktop

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

Cursor

Global: ~/.cursor/mcp.json · Por proyecto: .cursor/mcp.json

Windsurf

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

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

VS Code — GitHub Copilot

Archivo: .vscode/mcp.json (por proyecto) o mediante User Settings → MCP.

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

ChatGPT Desktop

Archivo: %APPDATA%\ChatGPT\claude_desktop_config.json (Windows) · ~/Library/Application Support/ChatGPT/claude_desktop_config.json (macOS). Requiere la aplicación de escritorio ChatGPT con soporte MCP habilitado.

Continue.dev

Archivo: ~/.continue/config.json (global) · .continue/config.json (por proyecto)

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

Zed

Archivo: ~/.config/zed/settings.json — añada a la clave context_servers.

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

Zed actualmente solo admite transporte stdio. Descargue stdio-bridge.php y actualice la ruta en consecuencia.

Gemini (Google AI Studio)

En Google AI Studio, vaya a Settings → Tools → Add MCP Server e introduzca la URL del endpoint directamente:

El soporte MCP nativo en los productos Gemini está en evolución — consulte la documentación de Google AI para conocer los últimos pasos de configuración.

Protocolo JSON-RPC 2.0

Formato de solicitud

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

Respuesta de éxito

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

Respuesta de error

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

Métodos disponibles

Método	Descripción
initialize	Protocolo de inicio — devuelve la versión del protocolo y las capacidades
ping	Comprobación de estado — devuelve un objeto vacío
tools/list	Lista todas las herramientas registradas con sus esquemas
tools/call	Ejecuta una herramienta con los argumentos proporcionados

Método — initialize

Protocolo de inicio obligatorio para establecer la sesión MCP. Debe ser la primera solicitud.

Solicitud

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

Respuesta

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

Método — ping

Comprueba que el servidor es accesible. No requiere parámetros.

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

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

Método — tools/list

Devuelve todas las herramientas registradas con su nombre, descripción y esquema de entrada (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
    ]
  }
}

Método — tools/call

Ejecuta una herramienta. El campo name identifica la herramienta; arguments contiene los parámetros según el esquema.

// 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 contiene una cadena JSON con los datos devueltos por la API de ifthenpay. Cuando isError es true, text contiene el mensaje de error.

multibanco_create_reference POST

Crea una referencia de pago Multibanco para el pago en cualquier cajero automático portugués o banca en línea.

Entrada

Campo	Tipo	Req.	Descripción
mb_key	string	Obligatorio	Clave Multibanco de ifthenpay
order_id	string	Obligatorio	Identificador de pedido único
amount	number	Obligatorio	Importe en EUR (p. ej. 10.50)
expiry_days	integer	Opcional	Días hasta que caduque la referencia; omitir para sin caducidad

Salida (content[0].text — JSON)

Campo	Tipo	Descripción
entity	string	Entidad Multibanco (5 dígitos)
reference	string	Referencia de pago (9 dígitos)
amount	string	Importe del pago
expiry_date	string|null	Fecha de caducidad (YYYYMMDD) o null
request_id	string	Identificador de solicitud único

Ejemplo

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

Envía una solicitud de pago al teléfono del cliente mediante la aplicación MB WAY. El cliente dispone de 4 minutos para aprobarla.

Entrada

Campo	Tipo	Req.	Descripción
mbway_key	string	Obligatorio	Clave MB WAY de ifthenpay
order_id	string	Obligatorio	Identificador de pedido único
amount	number	Obligatorio	Importe en EUR (p. ej. 10.50)
phone	string	Obligatorio	Número de teléfono en formato 351#912345678 (código de país#número)
description	string	Opcional	Descripción mostrada en la aplicación MB WAY

Salida

Campo	Tipo	Descripción
request_id	string	Token para consultar el estado mediante mbway_check_status
status	string	Estado inicial — siempre "pending"
message	string	Mensaje de estado

Ejemplo

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

Comprueba el estado de una solicitud de pago MB WAY. Utilice el request_id devuelto por mbway_request_payment.

Entrada

Campo	Tipo	Req.	Descripción
mbway_key	string	Obligatorio	Clave MB WAY de ifthenpay
request_id	string	Obligatorio	ID de solicitud devuelto por la solicitud de pago

Salida

Campo	Tipo	Descripción
status	string	paid | rejected	expired	declined	pending	unknown
status_code	string	Código API bruto: 000=paid, 020=rejected, 101=expired, 122=cancelled
message	string	Mensaje de estado
created_at	string|null	Marca de tiempo de creación
updated_at	string|null	Marca de tiempo de última actualización

Ejemplo

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

Genera una referencia Payshop para pago en efectivo en más de 5.000 agentes, oficinas de correos CTT y tiendas de conveniencia en Portugal.

Entrada

Campo	Tipo	Req.	Descripción
payshop_key	string	Obligatorio	Clave Payshop de ifthenpay
order_id	string	Obligatorio	Identificador de pedido único (máx. 25 caracteres)
amount	number	Obligatorio	Importe en EUR (p. ej. 10.50)
expiry_date	string	Opcional	Fecha de caducidad en formato YYYYMMDD; omitir para sin caducidad

Salida

Campo	Tipo	Descripción
reference	string	Referencia Payshop (13 dígitos)
request_id	string	Identificador de solicitud único
amount	string	Importe del pago

Ejemplo

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

Crea una sesión de pago alojada con tarjeta de crédito/débito. Admite Visa y Mastercard.

Cuando se invoca a través del agente de IA, este método se redirige a pinpay_create_payment con selected_method="4". La invocación directa mediante MCP conserva el comportamiento original.

Entrada

Campo	Tipo	Req.	Descripción
ccard_key	string	Obligatorio	Clave de Tarjeta de Crédito de ifthenpay
order_id	string	Obligatorio	Identificador de pedido único (máx. 15 caracteres)
amount	number	Obligatorio	Importe en EUR
success_url	string	Obligatorio	URL tras el pago correcto
error_url	string	Obligatorio	URL en caso de fallo del pago
cancel_url	string	Obligatorio	URL si el cliente cancela
language	string	Opcional	Idioma del proceso de pago: "pt" o "en"; predeterminado: "pt"

Salida

Campo	Tipo	Descripción
payment_url	string	URL del proceso de pago alojado
request_id	string	Identificador de solicitud único
amount	string	Importe del pago

pinpay_create_payment POST

Crea un enlace de pago PinPay (Pago por Enlace) que admite múltiples métodos de pago. Devuelve una URL y un código PIN para que el cliente acceda al proceso de pago.

Entrada

Campo	Tipo	Requerido	Descripción
gateway_key	string	Requerido	Clave de pasarela ifthenpay
order_id	string	Requerido	Identificador único de pedido (máx. 15 caracteres)
amount	number	Requerido	Importe (EUR o BRL para PIX)
accounts	string	Opcional	Métodos separados por punto y coma en formato MÉTODO|CLAVE — ver tabla a continuación
selected_method	string	Opcional	Preselecciona un método: 1=MB, 2=MBWAY, 3=Payshop, 4=Tarjeta, 7=Cofidis, 8=PIX. Omitir cuando hay múltiples métodos.
otp	string	Opcional	Pago de un solo uso: "true" — el enlace caduca después de un uso
expiry_date	string	Opcional	Fecha de caducidad del enlace en formato YYYYMMDD
description	string	Opcional	Descripción en la página de pago (máx. 200 caracteres)
lang	string	Opcional	Idioma: "pt", "en", "es", "fr"
success_url	string	Opcional	URL después del pago exitoso
error_url	string	Opcional	URL en caso de fallo del pago
cancel_url	string	Opcional	URL si el cliente cancela
btn_close_url	string	Opcional	URL para el botón de cierre en la página de pago
btn_close_label	string	Opcional	Etiqueta para el botón de cierre

Prefijos de método para el campo accounts

Método	Prefijo	selected_method
Multibanco	MB|{mb_key}	1
MB WAY	MBWAY|{mbway_key}	2
Payshop	PAYSHOP|{payshop_key}	3
Tarjeta de crédito	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

Ejemplo con todos los métodos:

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

Salida

Campo	Tipo	Descripción
redirect_url	string	URL de pago para compartir con el cliente
pinpay_url	string|null	URL directa de pinpay.pt
pin_code	string|null	Código PIN para acceder al pago
amount	string	Importe del pago

Ejemplo — enlace de tarjeta de crédito de un solo uso

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

Crea un pago a plazos de Cofidis Pay. Disponible principalmente en Portugal y España.

Cuando se invoca a través del agente de IA, este método se redirige a pinpay_create_payment con accounts="COFIDIS|{cofidis_key}" y selected_method="7".

Entrada

Campo	Tipo	Requerido	Descripción
cofidis_key	string	Requerido	Clave de Cofidis Pay de ifthenpay
order_id	string	Requerido	Identificador único de pedido (máx. 15 caracteres)
amount	number	Requerido	Importe en EUR (sujeto a los límites de Cofidis)
return_url	string	Requerido	URL de retorno; la API añade &Success=True al aprobarse
description	string	Opcional	Descripción o referencia del pago
customer_name	string	Opcional	Nombre completo del cliente
customer_email	string	Opcional	Correo electrónico del cliente
customer_phone	string	Opcional	Teléfono con código de país (p. ej. +351256245560)

Salida

Campo	Tipo	Descripción
payment_url	string	URL de pago de Cofidis
request_id	string	Identificador único de solicitud
amount	string	Importe del pago

pix_create_payment POST

Crea un pago PIX para clientes brasileños. Requiere el CPF del cliente.

Cuando se invoca a través del agente de IA, este método se redirige a pinpay_create_payment con accounts="PIX|{pix_key}" y selected_method="8".

Entrada

Campo	Tipo	Requerido	Descripción
pix_key	string	Requerido	Clave PIX de ifthenpay
order_id	string	Requerido	Identificador único de pedido (máx. 25 caracteres)
amount	number	Requerido	Importe en BRL (p. ej. 50.00)
redirect_url	string	Requerido	URL de retorno después del pago
customer_name	string	Requerido	Nombre completo del cliente (máx. 150 caracteres)
customer_cpf	string	Requerido	CPF — solo dígitos (p. ej. 74026594025)
customer_email	string	Requerido	Correo electrónico del cliente
customer_phone	string	Requerido	Teléfono con código de país (p. ej. +5585912345678)
description	string	Opcional	Descripción (máx. 200 caracteres)
customer_address	string	Opcional	Dirección
customer_city	string	Opcional	Ciudad
customer_state	string	Opcional	Estado (p. ej. CE, SP)
customer_zip_code	string	Opcional	Código postal

Salida

Campo	Tipo	Descripción
request_id	string	Identificador único de solicitud
payment_url	string	URL de pago
qr_code_value	string|null	Valor del código QR PIX
amount	string	Importe del pago

payments_list POST

Lista los pagos completados mediante la clave de Backoffice. Admite filtrado por método, fechas, ID de pedido, referencia o ID de solicitud. Devuelve hasta 1,000 registros sin filtros.

Entrada

Campo	Tipo	Requerido	Descripción
bo_key	string	Requerido	Clave de Backoffice de ifthenpay (proporcionada en su contrato)
entity	string	Opcional	Filtro de método: MB, MBWAY, PAYSHOP, CCARD, COFIDIS, GOOGLE, APPLE, PIX, o número de entidad (5 dígitos). Omitir para todos.
sub_entity	string	Opcional	Clave de método o subentidad
order_id	string	Opcional	Filtrar por ID de pedido
reference	string	Opcional	Filtrar por referencia
request_id	string	Opcional	Filtrar por ID de solicitud
amount	string	Opcional	Filtrar por importe exacto
date_start	string	Opcional	Fecha de inicio: dd-MM-yyyy HH:mm:ss
date_end	string	Opcional	Fecha de fin: dd-MM-yyyy HH:mm:ss

Salida

Campo	Tipo	Descripción
count	integer	Número de registros devueltos
payments	array	Lista de objetos de pago

Ejemplo — pagos MB de junio de 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
  }
}

Errores

Errores HTTP

HTTP	Causa
405	Método HTTP no permitido — solo se acepta POST

Errores JSON-RPC

Código	Significado
-32700	Error de análisis — JSON no válido
-32600	Solicitud no válida — faltan campos obligatorios
-32601	Método no encontrado — método desconocido
-32602	Parámetros no válidos — herramienta no encontrada o argumentos no válidos
-32603	Error interno — error inesperado del servidor

Errores de herramienta (isError: true)

Cuando una herramienta falla, la respuesta tiene isError: true y content[0].text contiene el mensaje:

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