Flutterwave

Interaja com a API do Flutterwave para gerenciar transações, gerar links de pagamento e lidar com suporte ao cliente.

Documentação

mcp-flutterwave

CI npm version npm downloads Docker License: MIT Node.js MCP

Um servidor MCP (Model Context Protocol) que permite que assistentes de IA interajam com a API da Flutterwave — criar links de pagamento, cobrar clientes diretamente, gerenciar transferências, receber via contas virtuais, pagar contas e muito mais.

Nota: Este servidor atualmente tem como alvo a API v3 da Flutterwave. O suporte para v4 está chegando em breve.

Também inclui um aplicativo web integrado que se conecta ao servidor MCP e permite conversar com um assistente Flutterwave com tecnologia Claude diretamente no seu navegador.


Conteúdo


Recursos

  • Checkout — Criar links de pagamento hospedados e desativá-los
  • Cobranças Diretas — Cobrar clientes via cartão, conta bancária, dinheiro móvel, M-Pesa ou USSD
  • Fluxo completo de autenticação de cartão — PIN, AVS (Verificação de Endereço), redirecionamento 3D Secure e validação de OTP tratados automaticamente
  • Validação de Cobrança — Validar cobranças baseadas em OTP com uma ferramenta dedicada
  • Transações — Verificar por ID ou referência, visualizar linha do tempo de eventos, reenviar webhooks com falha
  • Transferências — Iniciar transferências únicas, gerenciar beneficiários
  • Planos de Pagamento — Criar e recuperar planos de assinatura
  • Contas Virtuais — Gerar números de conta dedicados para cobrança de transferência bancária em NGN e GHS (estática ou dinâmica)
  • Pagamento de Contas — Pagar recarga, dados, TV a cabo, eletricidade, internet e mais (Nigéria)
  • Negociação de Câmbio (FX) — Converter entre NGN, GHS e USD com cotações em tempo real (RFQ → negociação em duas etapas)
  • Verificação — Verificação de identidade BVN, resolução de nome de conta bancária e consulta de BIN de cartão
  • Stablecoins — Enviar USDC/USDT para carteiras Polygon, ou converter moeda fiduciária NGN/USD em stablecoins
  • UI Rica — Cada ferramenta retorna um cartão HTML com marca renderizado inline em clientes compatíveis
  • Aplicativo Web — Uma interface de chat de navegador independente alimentada por Claude + este servidor MCP

Instalação

npm

npm install -g mcp-flutterwave

npx (sem necessidade de instalação)

npx mcp-flutterwave --tools=all

Docker

Puxe a imagem:

docker pull ghcr.io/bajoski34/mcp-flutterwave:latest

O servidor se comunica via stdio, portanto deve ser iniciado por um cliente MCP — não executado de forma independente. Configure o Claude Desktop para usar a imagem Docker como servidor MCP:

{
  "mcpServers": {
    "flutterwave": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "FLW_SECRET_KEY=YOUR_SECRET_KEY",
        "-e", "FLW_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY",
        "ghcr.io/bajoski34/mcp-flutterwave:latest"
      ]
    }
  }
}

A flag -i mantém o stdin aberto para que o Claude Desktop possa se comunicar com o servidor via stdio.

Requisitos: Node.js 20 ou posterior (para npm/npx).


Ferramentas Disponíveis

Checkout

FerramentaDescrição
create_checkoutCriar um link de pagamento Flutterwave hospedado
disable_checkoutDesativar um link de pagamento existente

Cobranças Diretas

FerramentaDescrição
charge_cardCobrar diretamente um cartão de débito ou crédito — lida com fluxos de PIN, AVS, 3DS e OTP
charge_bank_accountDebitar uma conta bancária (NGN / GHS)
charge_mobile_moneyDinheiro móvel — Gana, Uganda, Ruanda, Zâmbia, África Francófona
charge_mpesaCobrança M-Pesa (KES)
charge_ussdCobrança USSD (NGN)
validate_chargeValidar uma cobrança pendente usando OTP

Transações

FerramentaDescrição
read_transactionObter detalhes da transação por ID
read_transaction_with_referenceObter detalhes da transação por tx_ref
read_transaction_timelineVisualizar a linha do tempo de eventos de uma transação
resend_transaction_webhookReenviar um webhook com falha

Transferências

FerramentaDescrição
create_transferIniciar uma transferência bancária
create_beneficiarySalvar um novo beneficiário de transferência
list_beneficiariesListar todos os beneficiários salvos

Planos de Pagamento

FerramentaDescrição
create_payment_planCriar um plano de pagamento recorrente
get_payment_plansListar planos de pagamento com filtros opcionais

Contas Virtuais

FerramentaDescrição
create_virtual_accountCriar um número de conta bancária dedicado para um cliente (NGN ou GHS)
get_virtual_accountRecuperar o status e os detalhes de uma conta virtual por order_ref
update_virtual_accountVincular ou atualizar o BVN em uma conta virtual NGN
list_virtual_account_bulkListar todas as contas criadas em um lote em massa

Pagamento de Contas

FerramentaDescrição
get_bill_categoriesListar categorias de contas disponíveis (AIRTIME, CABLEBILLS, UTILITYBILLS, etc.)
get_bill_providersListar cobradores/provedores para uma categoria
get_bill_itemsListar itens pagáveis para um cobrador específico
validate_bill_customerValidar a conta de um cliente antes do pagamento (número do medidor, smartcard, etc.)
pay_billEnviar um pagamento de conta
get_bill_statusVerificar o status do pagamento e recuperar tokens pré-pagos (eletricidade)

Negociação de Câmbio (FX)

FerramentaDescrição
request_fx_quoteEnviar uma Solicitação de Cotação (RFQ) para conversão de moeda
get_fx_quoteConsultar o status da cotação — aguarde READY antes de negociar
initiate_fx_tradeBloquear uma cotação READY e executar a negociação
get_fx_tradeConsultar o status da negociação até SETTLED ou FAILED

Verificação

FerramentaDescrição
initiate_bvn_verificationIniciar uma verificação de identidade BVN — retorna uma URL de consentimento do cliente de uso único
get_bvn_detailsRecuperar dados completos de identidade BVN após o consentimento ser dado
resolve_bank_accountConsultar o nome do titular da conta para um número de conta bancária
verify_card_binConsultar marca, tipo, emissor e país do cartão a partir dos primeiros 6 dígitos

Stablecoins

FerramentaDescrição
get_stablecoin_feeObter a taxa de transferência antes de enviar — mostra o valor líquido que o destinatário recebe
send_stablecoinEnviar USDC ou USDT para um endereço de carteira Polygon
convert_to_stablecoinConverter saldo fiduciário em NGN ou USD para USDC ou USDT

Fluxo de Cobrança com Cartão

Cobranças diretas com cartão são de várias etapas. A ferramenta charge_card lida com cada etapa automaticamente e diz ao Claude o que fazer em seguida.

1. charge_card(card details)
        │
        ├─ mode: "pin"        → ask customer for PIN
        │       charge_card(same params + authorization: { mode: "pin", pin: "..." })
        │               │
        │               ├─ mode: "otp"      → validate_charge(flw_ref, otp)
        │               └─ mode: "redirect" → send customer to 3DS URL
        │
        ├─ mode: "avs_noauth" → ask customer for billing address
        │       charge_card(same params + authorization: { mode: "avs_noauth", city, address, ... })
        │               │
        │               ├─ mode: "otp"      → validate_charge(flw_ref, otp)
        │               └─ mode: "redirect" → send customer to 3DS URL
        │
        ├─ mode: "redirect"   → send customer to 3DS URL, then read_transaction to verify
        │
        └─ (none)             → charge complete — read_transaction to verify

Parâmetros de autorização

Quando uma segunda chamada for necessária, passe authorization junto com os detalhes originais do cartão:

// PIN flow
{ "authorization": { "mode": "pin", "pin": "3310" } }

// AVS flow
{ "authorization": { "mode": "avs_noauth", "city": "Lagos", "address": "12 Victoria Island", "state": "LA", "country": "NG", "zipcode": "100001" } }

Cartões AMEX

Transações com American Express exigem o campo card_holder_name além dos detalhes padrão do cartão.

Criptografia de payload

Os payloads de cartão são criptografados com 3DES-ECB usando sua FLW_ENCRYPTION_KEY antes de serem enviados à Flutterwave (requisito PCI DSS). A criptografia é tratada automaticamente — defina a variável de ambiente e o servidor faz o resto.


Contas Virtuais

Contas virtuais dão a cada cliente um número de conta bancária dedicado para receber transferências. A Flutterwave notifica seu webhook quando um pagamento chega.

RecursoNGNGHS
Dinâmica (uso único)✓ — defina amount, expira em ~1 hora✓ — use frequency e duration
Estática (reutilizável)✓ — is_permanent: true, BVN obrigatório✓ — is_permanent: true
BVN obrigatórioApenas contas estáticasNão

Conta estática NGN

{
  "email": "customer@example.com",
  "currency": "NGN",
  "tx_ref": "VA-NGN-001",
  "is_permanent": true,
  "bvn": "22415929481"
}

Conta dinâmica GHS

{
  "email": "customer@example.com",
  "currency": "GHS",
  "tx_ref": "VA-GHS-001",
  "amount": 500,
  "frequency": 5,
  "duration": 7
}

Após a criação, salve o order_ref — é a chave para recuperar ou atualizar a conta via get_virtual_account e update_virtual_account.


Fluxo de Pagamento de Contas

Os pagamentos de contas seguem um fluxo de descoberta em 6 etapas. Pule validate_bill_customer para recarga e dados móveis.

1. get_bill_categories
        ↓ choose a category (e.g. UTILITYBILLS)

2. get_bill_providers(category)
        ↓ get biller_code (e.g. "BIL127" for IKEDC)

3. get_bill_items(biller_code)
        ↓ get item_code and amount info

4. validate_bill_customer(item_code, customer_id)   ← skip for AIRTIME / MOBILEDATA
        ↓ confirm customer name and details

5. pay_bill(biller_code, item_code, customer_id, amount)
        ↓ returns reference

6. get_bill_status(reference)
        ↓ confirms completion
          for electricity: prepaid token is in extra.token — share it with the customer

Categorias suportadas

CódigoDescrição
AIRTIMERecarga de celular
MOBILEDATACompra de pacote de dados
CABLEBILLSTV a cabo (DSTV, GOTV, StarTimes)
INTSERVICEAssinaturas de serviço de internet
UTILITYBILLSEletricidade (pré-pago e pós-pago)
TAXPagamentos de impostos governamentais
DONATIONSDoações de caridade
TRANSLOGTransporte / logística
DEALPAYPagamentos de negócios
RELINSTInstituições religiosas
SCHPBPagamentos escolares / educacionais

Os pagamentos de contas estão disponíveis apenas para a Nigéria (country: NG).


Fluxo de Negociação de Câmbio (FX)

A conversão de moeda usa um fluxo de duas etapas: cotação e depois negociação. As cotações são válidas por 5 minutos e disponíveis apenas em dias úteis (segunda a sexta).

1. request_fx_quote(base_currency, target_currency, quantity)
        ↓ returns quote_id, status: NEW

2. get_fx_quote(quote_id)   ← poll until READY or FAILED
        ↓ READY: contains rate, approved_quantity, total_value, expiry

3. initiate_fx_trade(quote_id, narration)
        ↓ locks in rate, returns trade_id, status: NEW

4. get_fx_trade(trade_id)   ← poll until SETTLED or FAILED
        ↓ SETTLED: converted funds credited to target currency wallet instantly

Pares de moedas suportados

ParVendeRecebe
NGN/USDNaira NigerianaDólar Americano
GHS/USDCedi GanêsDólar Americano
USD/NGNDólar AmericanoNaira Nigeriana

Status de cotação

StatusSignificado
NEWA cotação está sendo precificada
READYTaxa bloqueada — chame initiate_fx_trade agora
PROCESSINGUma negociação foi iniciada nesta cotação
EXPIREDJanela de 5 minutos passou — envie uma nova cotação
FAILEDPar não suportado, mínimo não atingido ou limite de conta excedido

Status de negociação

StatusSignificado
NEWNegociação na fila
PENDINGExecutando
SETTLEDFundos trocados e creditados na carteira da moeda alvo
FAILEDSaldo insuficiente ou erro de processamento

Restrições principais

  • Negociação mínima: equivalente a $1.000 USD na moeda base
  • Vida útil da cotação: 5 minutos a partir da emissão (estado READY)
  • Uso único: cada cotação pode ser usada apenas para uma negociação
  • Quantidade aprovada: pode diferir da quantidade solicitada devido a liquidez ou limites de conta — sempre use approved_quantity para reconciliação
  • Habilitação da conta: entre em contato com hi@flutterwavego.com para habilitar negociação de câmbio na sua conta

Verificação

Resolução de Conta Bancária

Verifique os detalhes da conta de um destinatário antes de enviar uma transferência. Sempre mostre o nome resolvido ao usuário antes de prosseguir.

{ "account_number": "0690000040", "account_bank": "044" }

Códigos bancários comuns: 044 Access Bank · 057 Zenith Bank · 058 GTBank · 033 UBA · 011 First Bank

Consulta de BIN de Cartão

Identifique metadados do cartão a partir dos primeiros 6 dígitos do número do cartão.

{ "bin": "553188" }
// → { brand: "MASTERCARD", type: "CREDIT", issuer: "NEXUS MERCHANT BANK", country: "NIGERIA" }

Cartões AMEX identificados via BIN exigem o campo card_holder_name ao chamar charge_card.

Verificação BVN (Nigéria)

Fluxo de consentimento em duas etapas — o cliente deve aprovar o compartilhamento de dados no portal NIBSS.

1. initiate_bvn_verification(bvn, firstname, lastname, redirect_url)
        ↓ returns reference + single-use consent URL

2. Customer visits consent URL → approves data sharing on NIBSS portal
        ↓ webhook (bvn.completed) fires OR poll:

3. get_bvn_details(reference)
        ↓ returns name, DOB, gender, phone, NIN, state of origin, watchlist status

Requer habilitação da conta Flutterwave — entre em contato com hi@flutterwavego.com. Se o cliente já consentiu, initiate_bvn_verification retorna url: null e você pode chamar get_bvn_details imediatamente.


Stablecoins

Envie USDC ou USDT pela rede Polygon, ou converta saldos fiduciários em NGN/USD para stablecoins. Sempre chame get_stablecoin_fee primeiro para que o usuário saiba o valor líquido que o destinatário receberá.

Transferência de carteira para carteira

1. get_stablecoin_fee(amount, currency: "USDT", debit_currency: "USDT")
        ↓ shows fee and net amount

2. send_stablecoin(wallet_address, amount, currency, debit_currency)
        ↓ returns reference and transfer status

Conversão de fiduciário para stablecoin

1. get_stablecoin_fee(amount, currency: "USDC", debit_currency: "NGN")
        ↓ shows fee (percentage-based) and net USDC amount

2. convert_to_stablecoin(merchant_id, amount, currency, debit_currency: "NGN")
        ↓ deducts NGN from your fiat wallet, credits USDC/USDT

Restrições principais

RestriçãoDetalhe
RedeApenas Polygon — sem Tron, Solana ou Stellar
MoedasUSDC e USDT
Formato da carteiraEndereço EVM: 0x + 40 caracteres hexadecimais (42 no total)
Fontes fiduciáriasNGN ou USD para convert_to_stablecoin; stablecoin deve corresponder a currency para send_stablecoin
Tipo de taxaTaxa fixa para mesma moeda; taxa percentual para fiduciário → stablecoin

Aplicativo Web

O diretório app/ contém uma interface de chat de navegador independente que envolve este servidor MCP com um loop de conversação alimentado por Claude.

Flutterwave MCP-UI Components

Como funciona

Browser  →  POST /api/chat
               ↓
           Claude (Sonnet) — all MCP tools injected via advanced-tool-use beta
               ↓  tool_use
           MCP Server (this repo, spawned via stdio)
               ↓
           Flutterwave API

O aplicativo web usa três recursos de Uso Avançado de Ferramentas da Anthropic:

  • Pesquisa de Ferramentas — ferramentas não essenciais são adiadas e carregadas sob demanda, reduzindo o uso de tokens em ~85%
  • Chamada Programática de Ferramentas — Claude pode escrever código que chama múltiplas ferramentas em sequência sem inflar o contexto da conversa
  • Exemplos de Uso de Ferramentas — exemplos selecionados input_examples para cada ferramenta melhoram a precisão dos parâmetros de ~72% para ~90%

O aplicativo retorna um cartão de UI rico e personalizado para cada resposta de ferramenta — links de checkout, detalhes de transação, estados de cobrança, resumos de transferência, contas virtuais, recibos de contas — renderizados inline no chat.

Executando o aplicativo web

Pré-requisitos

VariávelObrigatóriaDescrição
FLW_SECRET_KEYSimSua chave secreta Flutterwave
FLW_ENCRYPTION_KEYPara cobranças com cartãoSua chave de criptografia Flutterwave
ANTHROPIC_API_KEYSimSua chave de API Anthropic

Obtenha suas chaves no Painel Flutterwave em Configurações → Chaves de API.
Obtenha sua chave Anthropic no Console Anthropic.

Compilar e iniciar

# Clone and install
git clone https://github.com/bajoski34/mcp-flutterwave.git
cd mcp-flutterwave
npm install

# Build both the MCP server and the web app
npm run build:all

# Start
ANTHROPIC_API_KEY=sk-ant-... FLW_SECRET_KEY=FLWSECK_... npm run start:app

Em seguida, abra http://localhost:3000.

Scripts disponíveis

ScriptDescrição
npm run buildCompila apenas o servidor MCP
npm run build:appCompila apenas o aplicativo web
npm run build:allCompila tudo
npm run start:appInicia o aplicativo web (requer compilação prévia)
npm run dev:appCompila tudo e inicia o aplicativo web
npm testExecuta a suíte de testes

Porta

Defina a variável de ambiente PORT para alterar o padrão 3000.


Configuração do Servidor MCP

Via npm

npm install -g mcp-flutterwave

Via GitHub

git clone https://github.com/bajoski34/mcp-flutterwave.git
cd mcp-flutterwave
npm install
npm run build

Variáveis de ambiente

VariávelObrigatóriaDescrição
FLW_SECRET_KEYSimSua chave secreta Flutterwave
FLW_ENCRYPTION_KEYPara cobranças com cartãoSua chave de criptografia Flutterwave (do Painel → Configurações → API)

Uso com Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json. Consulte o início rápido do MCP para detalhes.

Passe --tools=all para habilitar todas as ferramentas, ou forneça uma lista separada por vírgulas para restringir quais ferramentas são registradas.

Via npm

{
  "mcpServers": {
    "flutterwave": {
      "command": "mcp-flutterwave",
      "args": ["--tools=all"],
      "env": {
        "FLW_SECRET_KEY": "YOUR_SECRET_KEY",
        "FLW_ENCRYPTION_KEY": "YOUR_ENCRYPTION_KEY"
      }
    }
  }
}

Via compilação local

{
  "mcpServers": {
    "flutterwave": {
      "command": "node",
      "args": [
        "/path/to/mcp-flutterwave/build/index.js",
        "--tools=all"
      ],
      "env": {
        "FLW_SECRET_KEY": "YOUR_SECRET_KEY",
        "FLW_ENCRYPTION_KEY": "YOUR_ENCRYPTION_KEY"
      }
    }
  }
}

Ferramentas seletivas

"args": [
  "--tools=create_checkout,read_transaction,create_transfer"
]

Nomes de ferramentas aceitos (use all para habilitar tudo):

create_checkout            disable_checkout
read_transaction           read_transaction_with_reference
read_transaction_timeline  resend_transaction_webhook
create_transfer            create_beneficiary            list_beneficiaries
create_payment_plan        get_payment_plans
charge_card                charge_bank_account           charge_mobile_money
charge_mpesa               charge_ussd                   validate_charge
create_virtual_account     get_virtual_account           update_virtual_account
list_virtual_account_bulk
get_bill_categories        get_bill_providers            get_bill_items
validate_bill_customer     pay_bill                      get_bill_status
request_fx_quote           get_fx_quote
initiate_fx_trade          get_fx_trade
initiate_bvn_verification  get_bvn_details
resolve_bank_account       verify_card_bin
get_stablecoin_fee         send_stablecoin               convert_to_stablecoin

Componentes MCP-UI

Cada ferramenta retorna um cartão HTML rico junto com sua resposta de texto, alimentado por @mcp-ui/server. Os cartões usam os tokens de design da Flutterwave — azul-marinho #0A0E27, laranja profundo #FF5804, laranja da marca #F5A623 e a tipografia sans-serif do sistema.

Estados de UI para cobranças com cartão

EstadoCartão exibido
PIN necessárioInstruções passo a passo, referência da transação
AVS necessárioCampos obrigatórios de endereço de cobrança como chips
Redirecionamento 3DSURL de autenticação bancária com link direto
OTP necessárioMensagem do banco, flw_ref para passar para validate_charge
ConcluídoValor, selo de status, referências da transação e da Flutterwave

UI de conta virtual

O cartão de conta virtual mostra o número da conta bancária em uma caixa grande e proeminente, junto com o nome do banco, tipo de conta (Estática / Dinâmica), moeda, data de validade e referência do pedido.

UI de pagamento de contas

FerramentaCartão exibido
pay_billRecibo de conta — fornecedor, item, ID do cliente, valor, status
get_bill_statusCartão de status com token pré-pago (eletricidade) em texto monoespaçado grande, com nota de compartilhamento

UI de verificação

FerramentaCartão exibido
initiate_bvn_verificationCartão de consentimento — nome do cliente (apenas últimos 4 dígitos do BVN), link de consentimento de uso único com botão de abrir, instruções passo a passo
get_bvn_detailsCartão de identidade — nome, data de nascimento, gênero, telefone, NIN, estado de origem; BVN parcialmente mascarado; selo vermelho de lista de vigilância se sinalizado
resolve_bank_accountCartão verde de verificado — nome da conta em texto grande com número da conta e código do banco
verify_card_binCartão colorido da marca (azul Visa / vermelho Mastercard / azul Amex / escuro para outros) — marca, selo de tipo, emissor, país

UI de stablecoin

FerramentaCartão exibido
get_stablecoin_feeCartão de taxa com tema azul — par de moedas, taxa fixa ou detalhamento percentual, valor líquido que o destinatário recebe
send_stablecoinCartão de transferência — endereço de carteira truncado, valor, selo de status
convert_to_stablecoinCartão de conversão — moeda fiduciária de débito, stablecoin de destino, ID do comerciante, status

UI de negociação FX

Tanto request_fx_quote/get_fx_quote quanto initiate_fx_trade/get_fx_trade retornam cartões com tema azul-marinho escuro:

EstadoCartão exibido
Cotação NOVA / PROCESSANDOSelo de instrumento, pílula de status, instrução de consulta
Cotação PRONTATaxa de câmbio, quantidade aprovada, valor recebido, validade, chamada para ação
Cotação FALHOU / EXPIRADAMensagem de erro com motivo
Negociação NOVA / PENDENTEValor na moeda de destino, instrução de consulta
Negociação LIQUIDADABanner verde de liquidação, valor na moeda de destino, destinatário, nota de crédito na carteira
Negociação FALHOUBanner vermelho de falha com response_message

Os cartões são compatíveis com:

  • Aplicativo Web Flutterwave (app/ deste repositório) — renderizado inline no chat
  • MCP Inspector — para testes durante o desenvolvimento
  • Qualquer cliente MCP que suporte o tipo de conteúdo resource com HTML

Contribuindo

Aceitamos contribuições! Leia nosso Guia de Contribuição para detalhes sobre como começar, diretrizes de desenvolvimento e como enviar pull requests.


Changelog

Todas as mudanças notáveis estão documentadas em GitHub Releases.


Segurança

Se você descobrir uma vulnerabilidade de segurança, não abra uma issue pública. Em vez disso, envie um e-mail diretamente para olaobajua@gmail.com. Responderemos o mais rápido possível.


Licença

MIT © Abraham Olaobaju

Consulte LICENSE para o texto completo.