ifthenpay Payments MCP

Permite a agentes de IA generar pagos, recuperar el historial de transacciones e interactuar con los servicios de ifthenpay a través de MCP.

Ver en ifthenpay.comPrueba este MCPPatrocinado

Documentación

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 8 herramientas que cubren todos los métodos de pago de ifthenpay: Multibanco, MB WAY, Payshop, Tarjeta de Crédito, PinPay (Pago por Enlace), PIX y consulta de pagos.

Componente	Detalle
Protocolo	JSON-RPC 2.0 — HTTP Streamable (POST) + SSE (GET)
Versión MCP	`2025-03-26`
Nombre del servidor	`ifthenpay-mcp`
Versión del 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 `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

Use 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

Agregue 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 clientes

Cualquier cliente compatible con MCP puede conectarse usando el endpoint SSE. A continuación se presentan configuraciones listas para usar para las herramientas más comunes — no se requiere token de portador ni cabecera de autenticación para conectarse. Las credenciales necesarias para llamar a las herramientas de pago son sus propias claves de ifthenpay (Clave Multibanco, Clave MB WAY, Clave Gateway, Clave Backoffice, etc.), proporcionadas al contratar, pasadas como argumentos a cada llamada de herramienta.

Claude Desktop

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

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

Cursor

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

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

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.

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

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 — agregar 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 ingrese la URL del endpoint directamente:

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

El soporte MCP nativo en los productos Gemini está evolucionando — consulte la documentación de Google AI para conocer los pasos de configuración más recientes.

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`	Verificació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 */ }
  }
}

Respuesta de éxito

{
  "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 único de pedido
`amount`	number	Obligatorio	Importe en EUR (p. ej. `10.50`)
`expiry_days`	integer	Opcional	Días hasta que caduque la referencia; omitir para que no caduque

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 (AAAAMMDD) o `null`
`request_id`	string	Identificador único de solicitud

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 tiene 4 minutos para aprobar.

Entrada

Campo	Tipo	Req.	Descripción
`mbway_key`	string	Obligatorio	Clave MB WAY de ifthenpay
`order_id`	string	Obligatorio	Identificador único de pedido
`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. Use 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 sin procesar: `000` =pagado, `020` =rechazado, `101` =caducado, `122` =cancelado
`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 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 único de pedido (máx. 25 caracteres)
`amount`	number	Obligatorio	Importe en EUR (p. ej. `10.50`)
`expiry_date`	string	Opcional	Fecha de caducidad en formato AAAAMMDD; omitir para que no caduque

Salida

Campo	Tipo	Descripción
`reference`	string	Referencia Payshop (13 dígitos)
`request_id`	string	Identificador único de solicitud
`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 con tarjeta de crédito/débito alojada. 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 único de pedido (máx. 15 caracteres)
`amount`	number	Obligatorio	Importe en EUR
`success_url`	string	Obligatorio	URL después del pago exitoso
`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 único de solicitud
`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	Req.	Descripción
`gateway_key`	string	Obligatorio	Clave Gateway de ifthenpay
`order_id`	string	Obligatorio	Identificador único de pedido (máx. 15 caracteres)
`amount`	number	Obligatorio	Importe (EUR o BRL para PIX)
`accounts`	string	Opcional	Métodos separados por punto y coma en formato `METHOD\|KEY` — consulte la tabla a continuación
`selected_method`	string	Opcional	Preselecciona un método: `1` =MB, `2` =MBWAY, `3` =Payshop, `4` =Tarjeta, `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 AAAAMMDD
`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`
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};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 checkout
`amount`	string	Importe del pago

Ejemplo — enlace de tarjeta 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
  }
}

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	Req.	Descripción
`pix_key`	string	Obligatorio	Clave PIX de ifthenpay
`order_id`	string	Obligatorio	Identificador único del pedido (máx. 25 caracteres)
`amount`	number	Obligatorio	Importe en BRL (p. ej. `50.00`)
`redirect_url`	string	Obligatorio	URL de retorno tras el pago
`customer_name`	string	Obligatorio	Nombre completo del cliente (máx. 150 caracteres)
`customer_cpf`	string	Obligatorio	CPF — solo dígitos (p. ej. `74026594025`)
`customer_email`	string	Obligatorio	Correo electrónico del cliente
`customer_phone`	string	Obligatorio	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 de 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	Req.	Descripción
`bo_key`	string	Obligatorio	Clave de Backoffice de ifthenpay (proporcionada en su contrato)
`entity`	string	Opcional	Filtro por método: `MB`, `MBWAY`, `PAYSHOP`, `CCARD`, `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
  }
}