ifthenpay Payments MCP

Permitir que agentes

Ver em ifthenpay.comExperimente este MCPPatrocinado

Documentação

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

Visão Geral

O servidor MCP (Model Context Protocol) ifthenpay 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 8 ferramentas cobrindo todos os métodos de pagamento ifthenpay: Multibanco, MB WAY, Payshop, Cartão de Crédito, PinPay (Pay by Link), PIX e consulta de pagamentos.

Componente	Detalhe
Protocolo	JSON-RPC 2.0 — HTTP Streamable (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	HTTP Streamable (JSON-RPC)	Chamadas diretas à API, agentes, clientes MCP
GET	Stream SSE	Claude desktop e outros hosts MCP via configuração `url`

POST — HTTP Streamable

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 requisições retornam HTTP 200 com corpo JSON.

GET — Transporte SSE

Abre uma conexão persistente text/event-stream. O servidor envia imediatamente um evento endpoint com a URL POST e mantém o stream 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 ao 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

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

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 nas ferramentas mais comuns — nenhum token bearer ou cabeçalho de autenticação é necessário para conectar. As credenciais necessárias para chamar as ferramentas de pagamento são suas próprias chaves ifthenpay (Chave Multibanco, Chave MB WAY, Chave Gateway, Chave Backoffice, etc.), fornecidas na assinatura do contrato, passadas como argumentos em cada chamada de ferramenta.

Claude Desktop

Arquivo: %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 projeto: .cursor/mcp.json

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

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 User Settings → 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 desktop ChatGPT com suporte a MCP habilitado.

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

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 Settings → Tools → Add MCP Server e insira a URL do endpoint diretamente:

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

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 requisiçã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 schemas
`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 requisição.

Requisiçã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 schema 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 schema.

// Request
{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { /* tool parameters */ }
  }
}

Resposta de sucesso

{
  "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 ATM 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 requisiçã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 requisiçã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, estações 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 requisiçã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 do checkout hospedado
`request_id`	string	Identificador único da requisição
`amount`	string	Valor do pagamento

pinpay_create_payment POST

Cria um link de pagamento PinPay (Pay by Link) suportando 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 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 `METHOD\|KEY` — veja a tabela abaixo
`selected_method`	string	Opcional	Pré-seleciona um método: `1` =MB, `2` =MBWAY, `3` =Payshop, `4` =Cartão, `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 YYYYMMDD
`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`
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};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
  }
}

pix_create_payment POST

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

Quando invocado por meio do 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 por meio da 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`, `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
  }
}