ifthenpay Payments MCP

ifthenpay MCP — Payments

Documentação técnica do servidor MCP de pagamentos ifthenpay.
Cobre o protocolo de comunicação, todos os métodos disponíveis, o esquema de cada ferramenta e exemplos de solicitação/resposta.

Visão geral

O servidor ifthenpay MCP (Model Context Protocol) expõe as APIs de pagamento ifthenpay como ferramentas invocáveis para agentes de IA. Ele implementa o protocolo JSON-RPC 2.0 e a especificação MCP versão 2025-03-26.

O servidor é identificado como ifthenpay-mcp v1.0.0 e registra 9 ferramentas cobrindo todos os métodos de pagamento ifthenpay: Multibanco, MB WAY, Payshop, Credit Card, PinPay (Pay by Link), Cofidis Pay, PIX e consulta de pagamento.

Componente	Detalhe
Protocolo	JSON-RPC 2.0 — Streamable HTTP (POST) + SSE (GET)
Versão MCP	2025-03-26
Nome do servidor	ifthenpay-mcp
Versão do servidor	1.0.0

Endpoint

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

Dois transportes são suportados simultaneamente:

Método	Transporte	Caso de uso
POST	Streamable HTTP (JSON-RPC)	Chamadas diretas de API, agentes, clientes MCP
GET	Fluxo SSE	Claude desktop e outros hosts MCP via configuração de URL

POST — Streamable HTTP

Envie mensagens JSON-RPC 2.0 diretamente. Cabeçalho obrigatório:

Content-Type: application/json

Notificações (mensagens sem id) retornam HTTP 202 sem corpo. Todas as outras solicitações retornam HTTP 200 com corpo JSON.

GET — Transporte SSE

Abre uma conexão text/event-stream persistente. O servidor envia imediatamente um evento endpoint com a URL POST e mantém o fluxo ativo com pings periódicos:

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

: ping

Use este transporte ao conectar via Claude desktop ou qualquer host MCP que suporte a opção de configuração url — nenhum software local é necessário.

Configuração do Claude desktop

Adicione o seguinte a claude_desktop_config.json (localizado em %APPDATA%\Claude\ no Windows ou ~/Library/Application Support/Claude/ no 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

Solicitações preflight OPTIONS recebem uma resposta HTTP 200 imediata.

Integrações de Cliente

Qualquer cliente compatível com MCP pode se conectar usando o endpoint SSE. Abaixo estão configurações prontas para uso das ferramentas mais comuns. Se a autenticação estiver habilitada, adicione "headers": {"Authorization": "Bearer <token>"} a cada entrada.

Claude Desktop

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

Cursor

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

Windsurf

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

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

VS Code — GitHub Copilot

Arquivo: .vscode/mcp.json (por projeto) ou via Configurações do Usuário → MCP.

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

ChatGPT Desktop

Arquivo: %APPDATA%\ChatGPT\claude_desktop_config.json (Windows) · ~/Library/Application Support/ChatGPT/claude_desktop_config.json (macOS). Requer o aplicativo de desktop ChatGPT com suporte a MCP habilitado.

Continue.dev

Arquivo: ~/.continue/config.json (global) · .continue/config.json (por projeto)

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

Zed

Arquivo: ~/.config/zed/settings.json — adicione à chave context_servers.

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

O Zed atualmente suporta apenas transporte stdio. Baixe stdio-bridge.php e atualize o caminho de acordo.

Gemini (Google AI Studio)

No Google AI Studio, vá para Configurações → Ferramentas → Adicionar Servidor MCP e insira a URL do endpoint diretamente:

O suporte nativo a MCP nos produtos Gemini está em evolução — consulte a documentação do Google AI para as etapas de configuração mais recentes.

Protocolo JSON-RPC 2.0

Formato de solicitação

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

Resposta de sucesso

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

Resposta de erro

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

Métodos disponíveis

Método	Descrição
initialize	Handshake inicial — retorna versão do protocolo e capacidades
ping	Verificação de saúde — retorna um objeto vazio
tools/list	Lista todas as ferramentas registradas com seus esquemas
tools/call	Executa uma ferramenta com os argumentos fornecidos

Método — initialize

Handshake obrigatório para estabelecer a sessão MCP. Deve ser a primeira solicitação.

Solicitação

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

Resposta

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

Método — ping

Verifica se o servidor está acessível. Nenhum parâmetro é necessário.

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

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

Método — tools/list

Retorna todas as ferramentas registradas com nome, descrição e 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

Executa uma ferramenta. O campo name identifica a ferramenta; arguments contém os parâmetros de acordo com o 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 contém uma string JSON com os dados retornados pela API ifthenpay. Quando isError é true, text contém a mensagem de erro.

multibanco_create_reference POST

Cria uma referência de pagamento Multibanco para pagamento em qualquer caixa eletrônico português ou internet banking.

Entrada

Campo	Tipo	Obrig.	Descrição
mb_key	string	Obrigatório	Chave Multibanco ifthenpay
order_id	string	Obrigatório	Identificador único do pedido
amount	number	Obrigatório	Valor em EUR (ex.: 10.50)
expiry_days	integer	Opcional	Dias até a referência expirar; omita para sem expiração

Saída (content[0].text — JSON)

Campo	Tipo	Descrição
entity	string	Entidade Multibanco (5 dígitos)
reference	string	Referência de pagamento (9 dígitos)
amount	string	Valor do pagamento
expiry_date	string|null	Data de expiração (YYYYMMDD) ou null
request_id	string	Identificador único da solicitação

Exemplo

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

Envia uma solicitação de pagamento para o telefone do cliente via aplicativo MB WAY. O cliente tem 4 minutos para aprovar.

Entrada

Campo	Tipo	Obrig.	Descrição
mbway_key	string	Obrigatório	Chave MB WAY ifthenpay
order_id	string	Obrigatório	Identificador único do pedido
amount	number	Obrigatório	Valor em EUR (ex.: 10.50)
phone	string	Obrigatório	Número de telefone no formato 351#912345678 (código do país#número)
description	string	Opcional	Descrição exibida no aplicativo MB WAY

Saída

Campo	Tipo	Descrição
request_id	string	Token para consulta de status via mbway_check_status
status	string	Status inicial — sempre "pending"
message	string	Mensagem de status

Exemplo

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

Verifica o status de uma solicitação de pagamento MB WAY. Use o request_id retornado por mbway_request_payment.

Entrada

Campo	Tipo	Obrig.	Descrição
mbway_key	string	Obrigatório	Chave MB WAY ifthenpay
request_id	string	Obrigatório	ID da solicitação retornado pela solicitação de pagamento

Saída

Campo	Tipo	Descrição
status	string	paid | rejected	expired	declined	pending	unknown
status_code	string	Código bruto da API: 000=pago, 020=rejeitado, 101=expirado, 122=cancelado
message	string	Mensagem de status
created_at	string|null	Timestamp de criação
updated_at	string|null	Timestamp da última atualização

Exemplo

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

Gera uma referência Payshop para pagamento em dinheiro em mais de 5.000 agentes, agências dos CTT e lojas de conveniência em Portugal.

Entrada

Campo	Tipo	Obrig.	Descrição
payshop_key	string	Obrigatório	Chave Payshop ifthenpay
order_id	string	Obrigatório	Identificador único do pedido (máx. 25 caracteres)
amount	number	Obrigatório	Valor em EUR (ex.: 10.50)
expiry_date	string	Opcional	Data de expiração no formato YYYYMMDD; omita para sem expiração

Saída

Campo	Tipo	Descrição
reference	string	Referência Payshop (13 dígitos)
request_id	string	Identificador único da solicitação
amount	string	Valor do pagamento

Exemplo

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

Cria uma sessão de pagamento hospedada com cartão de crédito/débito. Suporta Visa e Mastercard.

Quando invocado através do agente de IA, este método é redirecionado para pinpay_create_payment com selected_method="4". A invocação direta via MCP mantém o comportamento original.

Entrada

Campo	Tipo	Obrig.	Descrição
ccard_key	string	Obrigatório	Chave de Cartão de Crédito ifthenpay
order_id	string	Obrigatório	Identificador único do pedido (máx. 15 caracteres)
amount	number	Obrigatório	Valor em EUR
success_url	string	Obrigatório	URL após pagamento bem-sucedido
error_url	string	Obrigatório	URL em caso de falha no pagamento
cancel_url	string	Obrigatório	URL se o cliente cancelar
language	string	Opcional	Idioma do checkout: "pt" ou "en"; padrão: "pt"

Saída

Campo	Tipo	Descrição
payment_url	string	URL de checkout hospedado
request_id	string	Identificador único da solicitação
amount	string	Valor do pagamento

pinpay_create_payment POST

Cria um link de pagamento PinPay (Pay by Link) com suporte a múltiplos métodos de pagamento. Retorna uma URL e um código PIN para o cliente acessar o checkout.

Entrada

Campo	Tipo	Obrig.	Descrição
gateway_key	string	Obrigatório	Chave de gateway ifthenpay
order_id	string	Obrigatório	Identificador único do pedido (máx. 15 caracteres)
amount	number	Obrigatório	Valor (EUR ou BRL para PIX)
accounts	string	Opcional	Métodos separados por ponto e vírgula no formato MÉTODO|CHAVE — veja a tabela abaixo
selected_method	string	Opcional	Pré-seleciona um método: 1=MB, 2=MBWAY, 3=Payshop, 4=Cartão, 7=Cofidis, 8=PIX. Omita quando houver múltiplos métodos.
otp	string	Opcional	Pagamento de uso único: "true" — o link expira após um uso
expiry_date	string	Opcional	Data de expiração do link no formato AAAAMMDD
description	string	Opcional	Descrição na página de pagamento (máx. 200 caracteres)
lang	string	Opcional	Idioma: "pt", "en", "es", "fr"
success_url	string	Opcional	URL após pagamento bem-sucedido
error_url	string	Opcional	URL em caso de falha no pagamento
cancel_url	string	Opcional	URL se o cliente cancelar
btn_close_url	string	Opcional	URL para o botão de fechar na página de pagamento
btn_close_label	string	Opcional	Rótulo para o botão de fechar

Prefixos de método para o campo accounts

Método	Prefixo	selected_method
Multibanco	MB|{mb_key}	1
MB WAY	MBWAY|{mbway_key}	2
Payshop	PAYSHOP|{payshop_key}	3
Cartão 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

Exemplo com todos os 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}"

Saída

Campo	Tipo	Descrição
redirect_url	string	URL de pagamento para compartilhar com o cliente
pinpay_url	string|null	URL direta do pinpay.pt
pin_code	string|null	Código PIN para acessar o checkout
amount	string	Valor do pagamento

Exemplo — link de cartão de crédito de uso único

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

Cria um pagamento parcelado Cofidis Pay. Disponível principalmente em Portugal e Espanha.

Quando invocado pelo agente de IA, este método é redirecionado para pinpay_create_payment com accounts="COFIDIS|{cofidis_key}" e selected_method="7".

Entrada

Campo	Tipo	Obrig.	Descrição
cofidis_key	string	Obrigatório	Chave Cofidis Pay ifthenpay
order_id	string	Obrigatório	Identificador único do pedido (máx. 15 caracteres)
amount	number	Obrigatório	Valor em EUR (sujeito aos limites da Cofidis)
return_url	string	Obrigatório	URL de retorno; a API acrescenta &Success=True na aprovação
description	string	Opcional	Descrição ou referência do pagamento
customer_name	string	Opcional	Nome completo do cliente
customer_email	string	Opcional	E-mail do cliente
customer_phone	string	Opcional	Telefone com código do país (ex.: +351256245560)

Saída

Campo	Tipo	Descrição
payment_url	string	URL do checkout Cofidis
request_id	string	Identificador único da solicitação
amount	string	Valor do pagamento

pix_create_payment POST

Cria um pagamento PIX para clientes brasileiros. Requer o CPF do cliente.

Quando invocado pelo agente de IA, este método é redirecionado para pinpay_create_payment com accounts="PIX|{pix_key}" e selected_method="8".

Entrada

Campo	Tipo	Obrig.	Descrição
pix_key	string	Obrigatório	Chave PIX ifthenpay
order_id	string	Obrigatório	Identificador único do pedido (máx. 25 caracteres)
amount	number	Obrigatório	Valor em BRL (ex.: 50.00)
redirect_url	string	Obrigatório	URL de retorno após o pagamento
customer_name	string	Obrigatório	Nome completo do cliente (máx. 150 caracteres)
customer_cpf	string	Obrigatório	CPF — apenas dígitos (ex.: 74026594025)
customer_email	string	Obrigatório	E-mail do cliente
customer_phone	string	Obrigatório	Telefone com código do país (ex.: +5585912345678)
description	string	Opcional	Descrição (máx. 200 caracteres)
customer_address	string	Opcional	Endereço
customer_city	string	Opcional	Cidade
customer_state	string	Opcional	Estado (ex.: CE, SP)
customer_zip_code	string	Opcional	Código postal

Saída

Campo	Tipo	Descrição
request_id	string	Identificador único da solicitação
payment_url	string	URL de pagamento
qr_code_value	string|null	Valor do QR code PIX
amount	string	Valor do pagamento

payments_list POST

Lista pagamentos concluídos via Chave de Backoffice. Suporta filtros por método, datas, ID do pedido, referência ou ID da solicitação. Retorna até 1.000 registros sem filtros.

Entrada

Campo	Tipo	Obrig.	Descrição
bo_key	string	Obrigatório	Chave de Backoffice ifthenpay (fornecida no seu contrato)
entity	string	Opcional	Filtro por método: MB, MBWAY, PAYSHOP, CCARD, COFIDIS, GOOGLE, APPLE, PIX, ou número da entidade (5 dígitos). Omita para todos.
sub_entity	string	Opcional	Chave do método ou subentidade
order_id	string	Opcional	Filtrar por ID do pedido
reference	string	Opcional	Filtrar por referência
request_id	string	Opcional	Filtrar por ID da solicitação
amount	string	Opcional	Filtrar por valor exato
date_start	string	Opcional	Data inicial: dd-MM-yyyy HH:mm:ss
date_end	string	Opcional	Data final: dd-MM-yyyy HH:mm:ss

Saída

Campo	Tipo	Descrição
count	integer	Número de registros retornados
payments	array	Lista de objetos de pagamento

Exemplo — pagamentos MB de junho 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
  }
}

Erros

Erros HTTP

HTTP	Causa
405	Método HTTP não permitido — apenas POST é aceito

Erros JSON-RPC

Código	Significado
-32700	Erro de análise — JSON inválido
-32600	Solicitação inválida — campos obrigatórios ausentes
-32601	Método não encontrado — método desconhecido
-32602	Parâmetros inválidos — ferramenta não encontrada ou argumentos inválidos
-32603	Erro interno — erro inesperado do servidor

Erros de ferramenta (isError: true)

Quando uma ferramenta falha, a resposta tem isError: true e content[0].text contém a mensagem:

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