Pular para o conteúdo principal
Neste guia você vai implementar pagamentos reais dentro de um app conversacional implantado no WhatsApp, usando o Mercado Pago.
Pré-requisitos:
  • Ter um fluxo no Brain Studio pronto (por exemplo, um Agente de IA que gerencia um processo de venda).
  • Ter uma conta no Mercado Pago (para obter credenciais de teste e produção).
Vamos usar como exemplo um app que vende ingressos para tours: o usuário escolhe o tour, a data, o número de ingressos e fornece seu email. Agora vamos habilitar cobranças com Mercado Pago dentro do mesmo fluxo. Este tutorial está dividido em três partes:
  1. Implementação em modo de teste (DEV)
  2. Testes no WhatsApp
  3. Ir para produção (PROD)

1. Implementação em modo de teste (DEV)

Vídeo 1: Instalação e configuração no Brain Studio

Vídeo 1 – Instalação do Mercado Pago + configuração do nó em modo de teste (DEV)


Configuração inicial

1

Copiar seu Access Token de teste

Primeira vez? Veja o guia passo a passo: Obtendo credenciais do Mercado Pago.
Abra sua conta do Mercado Pago e acesse Suas integrações.
Painel do Mercado Pago mostrando Suas integrações, seletor de aplicação Jelou, e os cards de Credenciais de produção e Credenciais de teste

Suas integrações no Mercado Pago: escolha sua aplicação e acesse Credenciais de Produção ou Credenciais de Teste

  • Acesse Credenciais de teste
  • Copie o Access Token
Você usará esse token para instalar o Mercado Pago no Brain Studio.
Token pronto para colar no Brain Studio.
2

Instalar o Mercado Pago pelo Marketplace

No Brain Studio:
  • Acesse o Marketplace
  • Pesquise por Mercado Pago
  • Clique em Conectar
  • Cole seu Access Token de teste
  • Clique em Instalar
Modal de Credenciais de API no Brain Studio solicitando o Access Token para instalar o Mercado Pago

Modal de instalação: cole seu Access Token do Mercado Pago e confirme

Após instalar, você verá o Mercado Pago disponível na pasta Marketplace no painel lateral do Canvas.
Mercado Pago visível no Marketplace.
3

Arrastar e conectar o nó ao Canvas

Conecte o fluxo de pagamento logo após o usuário confirmar sua compra ou reserva.
  • Dentro do Brain, encontre o Mercado Pago na pasta Marketplace no painel lateral e arraste-o para o canvas
  • Conecte-o após a etapa onde o usuário confirma sua compra ou reserva.
Em seguida, configure as entradas do nó. Os três campos obrigatórios são: motivo do pagamento, valor tributável e email do comprador.

Configurar Entradas: O que é cada campo?

Defina três coisas fundamentais no momento da cobrança:
  1. O que você está cobrando (motivo + valor + moeda)
  2. De quem você está cobrando (email do comprador)
  3. Sob quais regras (ambiente, impostos, expiração, metadados)
Pense nesta seção como a definição estrutural do pagamento: o que o Mercado Pago precisa para criar a transação corretamente.
Painel de configuração de entradas

Painel de configuração de entradas

Os nomes exatos podem variar ligeiramente dependendo do seu template, mas o padrão é sempre o mesmo: valor + moeda + impostos (se aplicável) + email do comprador + metadados opcionais.

O que você deve preencher

Antes de entrar nos detalhes, certifique-se de ter esses três elementos claros:
  • Um motivo de pagamento legível (ex.: “Valpo Walk Tour - 2 ingresso(s)”)
  • Um valor correto (líquido se você trabalha com impostos)
  • Um email de comprador válido (em DEV deve ser um usuário de teste)
Se esses três estiverem bem definidos, o restante é configuração.

Resumo das entradas do nó

Antes de entrar nos detalhes, existem duas ideias-chave:
  1. Este nó cria a cobrança (com valor, moeda, impostos, motivo e email).
  2. Este nó retorna uma resposta (JSON) que você pode reutilizar depois (por exemplo, para exibir um recibo ou salvar IDs de pagamento).

Salvar resultado como

No topo do nó você verá Salvar resultado como. Lá você define o nome com o qual o Brain Studio salvará a resposta completa da ferramenta como JSON na Memória.
  • Neste tutorial usamos: checkout_response
  • Você pode lê-lo depois em um nó Código com algo como:
    • const r = $memory.getJson('checkout_response')
Memória vs Contexto:
  • Memória persiste entre conversas (útil para consultar o status do pagamento depois).
  • Contexto está disponível apenas durante a conversa atual.
Para mais detalhes, veja o guia completo.

Detalhes de cada entrada

Abaixo está um guia prático sobre o que colocar em cada campo (na mesma ordem em que você verá no nó).

Tipo de pagamento (padrão: payment)

Deixe como payment, a menos que sua implementação tenha outro tipo habilitado/definido. Em um tutorial genérico, payment está correto.

Ambiente (DEV / PROD)

  • DEV: testes controlados com credenciais de teste.
  • PROD: cobranças reais com credenciais de produção.
Quando você mudar para PROD, verifique se seu fluxo já trata bem as saídas (sucesso, pendente, falhou, erros) para evitar deixar o usuário “sem resposta”.

Expiração do botão (minutos)

Exemplo típico: 20. Isso evita pagamentos fora de contexto (“abri 3 horas depois”) e ajuda o fluxo conversacional a permanecer coerente.

Moeda

Selecione a moeda real de cobrança de acordo com o país/operação. Exemplos: CLP, MXN, COP, PEN, etc.

Motivo do pagamento

Este é o texto que permite identificar facilmente a cobrança. Recomendação prática:
  • Use uma variável legível (ex.: mp_payment_description)
  • Ou texto claro como: Valpo Walk Tour - 2 ingresso(s)
Quanto mais “humano” for o motivo, menor é o atrito no suporte: o usuário e o lojista se entendem mais rápido quando algo dá errado.

Valor tributável + Valor isento + IVA

Aqui você define a estrutura do valor.
  • Valor tributável: a parte que paga IVA (normalmente o valor líquido).
  • Valor isento: a parte isenta (se não existir no seu caso, deixe como 0).
  • Percentual de IVA: por exemplo 19.
Exemplo típico (venda com IVA):
  • Valor tributável = líquido (ex.: 20168)
  • Valor isento = 0
  • IVA = 19
Se o seu caso NÃO usa impostos:
  • Use 0 conforme apropriado na sua implementação e mantenha consistência com seu cálculo (o importante é não “inventar” IVA se não se aplica).

Metadados do pagamento

Este campo é opcional, mas útil; permite anexar contexto para rastreabilidade. Recomendação: minimalista e intencional. Salve apenas o que você realmente usaria para:
  • reconciliação de pagamento
  • debugging
  • ou suporte ao usuário
Exemplos úteis:
  • order_id
  • order_reference_id (se seu backend usa)
  • tour_slug
  • user_id

Email do comprador (muito importante em DEV)

Em modo DEV é extremamente importante que o comprador seja um usuário de teste, conforme exigido pelo Mercado Pago. Neste tutorial assumimos:
  • email do comprador = email do pagador (são o mesmo)
Em DEV use o email do usuário de teste do país correspondente (a lista está abaixo). Em PROD, use o email real do usuário.
Se você está em DEV e coloca um email real (não de usuário de teste), o pagamento muito provavelmente falhará ou você não conseguirá concluí-lo.

Personalizar texto do botão de pagamento (opcional)

Por padrão vem como Não. Se você mudar para Sim, o nó habilita campos extras para personalizar a mensagem que o usuário verá antes de abrir o checkout. Isso é útil quando você quer que o CTA pareça mais contextual (e menos genérico), sem alterar o fluxo ou o próprio checkout.
Customize payment button text
boolean
padrão:"false"
Se você selecionar Sim, campos adicionais são habilitados para personalizar a mensagem que acompanha o botão de pagamento.Campos habilitados quando ativado:
  • Header (obrigatório)
  • Body (obrigatório)
  • Footer (obrigatório)
Quando esta opção está ativa, você pode modificar completamente a mensagem que o usuário verá antes de abrir o checkout.
Exemplo de mensagem com texto personalizado e botão de pagamento do Mercado Pago no WhatsApp

Exemplo de mensagem com botão de pagamento personalizado no WhatsApp


Emails de teste por país (modo de teste / DEV)

Em DEV, o Mercado Pago só processa pagamentos se o Email do comprador pertencer a um usuário de teste do país correspondente. Copie o que você precisar e cole diretamente no campo Email do comprador do nó.
Sempre use o usuário de teste do mesmo país que as credenciais que você está testando.
Se você está em DEV e o pagamento falha sem razão aparente, primeiro verifique se o email é um usuário de teste válido.

Configuração do nó: Saídas

O nó expõe diferentes saídas dependendo do status do pagamento.
Fluxo do nó Jelou Pay mostrando saídas: Pagamento bem-sucedido, Pagamento pendente, Pagamento falhou, Código de erro, Erro Http, e Entrega correta de CTA conectados a nós de Texto, Botão e suporte

Configuração de saídas do nó: Entrega correta de CTA, Pagamento bem-sucedido, Pendente, Falhou, Código de erro, Erro Http


Mapa rápido de saídas

  • Entrega correta de CTA → O botão foi enviado ao usuário (ainda sem resultado de pagamento).
  • Pagamento bem-sucedido → O pagamento foi aprovado.
  • Pagamento pendente → O pagamento foi iniciado mas ainda não creditado.
  • Pagamento falhou → O pagamento foi rejeitado ou não concluído.
  • Código de erro / Erro Http → Erro técnico do fluxo ou da solicitação.
CTA significa que o botão de pagamento foi enviado com sucesso. As outras saídas representam o resultado real da transação.

Saídas e o que conectar


Entrega correta de CTA (Sucesso)

Isso significa que o botão de pagamento foi enviado ao usuário, mas ele ainda não realizou uma ação dentro da WebView que determine o status da transação (Aprovado, Rejeitado, Pendente, Erro). Recomendação: conecte um Agente de IA de suporte pós-CTA. Assim, quando o usuário receber o botão de pagamento, haverá alguém do outro lado: um agente com o contexto adequado que pode responder perguntas frequentes, tranquilizá-lo e ajudar a concluir o pagamento sem reiniciar a venda.
Conversa no WhatsApp: agente oferece prosseguir com o pagamento, usuário aceita, agente envia botão do Mercado Pago e mensagem de suporte; usuário pergunta se aceitam cartão de crédito e agente responde gentilmente

Botão de pagamento, mensagem de suporte proativo e resposta a uma pergunta (cartão de crédito)

Exemplo de prompt

O prompt é projetado para um Agente de IA na saída de Entrega correta de CTA, com a ferramenta Gmail (Marketplace) conectada para enviar tickets de suporte por email quando o usuário solicitar. Você pode copiá-lo e ajustar o tom ou regras para sua marca.

Pagamento bem-sucedido

O pagamento foi aprovado. Recomendação:
  1. Conecte um nó Código para normalizar e salvar o mínimo no Contexto.
  2. Depois um nó Texto que exibe o recibo resumido (linha de recibo).

Exemplo: Código de normalização

Este nó lê checkout_response da memória e salva no contexto apenas o que é reutilizável.
normalize-payment.js
Se você usar este código, pode imprimir a mensagem ao usuário em um nó de saída Texto colando esta expressão:
Diagrama: saída Pagamento bem-sucedido do nó Jelou Pay conectada ao nó Código, e este ao nó Texto com pay_receipt

Fluxo Pagamento bem-sucedido → Código (normalização) → Texto (pay_receipt)


Pagamento pendente

O pagamento está pendente. Recomendação:
  • Conecte um nó Texto com uma breve explicação.
  • Depois roteie para o fluxo que vem a seguir (espera, acompanhamento, suporte, etc.).
Mantenha a mensagem simples: o objetivo é não confundir e não pressionar um segundo pagamento sem contexto.

Pagamento falhou

O pagamento falhou (rejeição / não creditado). Recomendação:
  • Conecte um nó Texto claro e breve.
  • Ofereça uma nova tentativa ou troca de método.
  • Se o usuário continuar tendo problemas, roteie para o suporte.

Código de erro / Erro Http

Erros técnicos do seu fluxo (código) ou da solicitação HTTP. Recomendação:
  • Conecte um bloco de tratamento de erros.
  • Exiba uma mensagem breve + opção de nova tentativa + suporte.
  • Evite expor detalhes técnicos ao usuário final.

2. Testes no WhatsApp

Após configurar o nó (entradas + saídas conectadas), é hora de testar o fluxo completo pelo WhatsApp.
Importante: A experiência de pagamento abre em um WebView dentro do WhatsApp. Portanto, para validar o pagamento de ponta a ponta, o teste deve ser feito pelo WhatsApp (não pela pré-visualização de mensagens do Canvas).

Vídeo 2: Testes pelo WhatsApp (DEV)

Vídeo 2 – Testes por celular com cartões de teste (DEV)


Como iniciar o teste pelo WhatsApp

No Brain Studio você pode iniciar um teste real no WhatsApp em segundos.
1

Abrir o painel de Teste

No canto superior direito do Canvas, clique em Testar.
Painel de teste do projeto no Brain Studio com a opção Testar pelo WhatsApp e campo de número de telefone

Painel de teste do projeto: inicie um teste pelo WhatsApp inserindo seu número

Se você ainda não tem um canal WhatsApp conectado/habilitado, esta é a forma mais rápida de validar o fluxo de pagamento.
2

Inserir seu número e enviar a primeira mensagem

  • Selecione seu prefixo (ex.: BR +55)
  • Insira seu número
  • Envie a primeira mensagem para iniciar a conversa de teste
A partir desse ponto, o fluxo funciona como se fosse um usuário real.
3

Concluir o pagamento no WebView

Quando o bot enviar o botão Prosseguir para pagamento, abra-o pelo WhatsApp.Lá você verá o checkout WebView e poderá testar cartões de teste, status (aprovado/rejeitado), e todo o tratamento de saídas.
Em alguns países, se o usuário tiver o app do Mercado Pago instalado no dispositivo, o checkout webview tentará abri-lo automaticamente como primeira opção de pagamento. No entanto, para pagamentos DEV esta opção não está habilitada, então você deve fechá-lo e voltar ao WhatsApp para inserir o cartão de teste.

Cartões de teste por país

Para testar diferentes cenários (pagamento aprovado, pagamento rejeitado, etc.), o Mercado Pago publica cartões de teste por país.
Em DEV, lembre de duas coisas:
  • Use credenciais de teste.
  • Use um usuário de teste válido no campo Email do comprador (do mesmo país que suas credenciais).
Cada link contém números de cartão, CVV e casos de aprovação/rejeição:
Se você quiser testar seu fluxo corretamente, experimente pelo menos 2 casos: um aprovado e um rejeitado. Isso valida que suas saídas (Pagamento bem-sucedido / Falhou) estão conectadas corretamente.

3. Ir para produção (PROD)

Ir para PROD é basicamente mudar duas coisas: credenciais e dados reais. A experiência no WhatsApp permanece a mesma, mas agora o pagamento afeta sua conta de produção.

Vídeo 3: Configuração de produção + pagamento real

Vídeo 3 – Indo para produção (PROD) e pagamento real

1

Obter credenciais de produção

No Mercado Pago, acesse Credenciais de produção e copie seu Access Token de produção.
Este token está associado à sua conta de produção. Use-o apenas quando estiver pronto para cobrar real.
2

Atualizar credenciais no Marketplace

Para evitar confusão (e ser explícito), vamos reinstalar a integração com o token correto:
  • Acesse o Marketplace
  • Abra o Mercado Pago
  • Pressione Excluir integração
  • Pressione Instalar novamente
  • Cole seu Access Token de produção
  • Pressione Instalar
3

Mudar o ambiente do nó para PROD

No nó Jelou Pay: Enviar link de pagamento:
  • Mude o Ambiente de DEV para PROD
A partir deste ponto, o fluxo tentará gerar cobranças reais.
4

Substituir o Email do comprador pelo email real do fluxo

Em DEV, usamos um usuário de teste no campo Email do comprador. Em PROD, esse mesmo campo deve vir do seu fluxo (o email real do usuário).Se durante a fase de teste você deixou um usuário de teste fixo na entrada, agora substitua pela sua variável.
Neste tutorial, o email é capturado durante a conversa (Agente de IA) e normalizado como variável antes de chegar ao nó de pagamento. O importante é que em PROD o campo Email do comprador esteja conectado a esses dados reais.
5

(Opcional) Personalizar texto do botão de pagamento

Se você quiser que o CTA pareça mais contextual (sem alterar o checkout), ative Personalizar texto do botão de pagamento.
  • Mude o seletor para Sim
  • Preencha Header, Body e Footer (obrigatórios)
Isso apenas personaliza a mensagem pré-checkout dentro do WhatsApp. A lógica de pagamento e o WebView não mudam.
6

Testar pagamento real

Faça um pagamento real (carteira ou cartão) e verifique:
  • Status Aprovado
  • Número de operação (operation ID)
  • Registro visível no seu painel do Mercado Pago
Transações de produção consomem créditos do Brain Studio por tentativa, além das comissões do provedor. Se você estiver validando pela primeira vez, faça uma cobrança pequena e revise o painel antes de escalar.

Próximos passos

Experiências de pagamento

Quando usar WebView, experiência nativa ou fluxos conversacionais.

Provedores de pagamento

Outros provedores por país e guias específicos.

Mercado Pago - Uso e configuração

Referência completa para entradas, saídas e opções do nó.

Com esses passos você tem o fluxo funcionando em teste e produção. A partir daqui você pode registrar operações, emitir recibos, enviar tickets de email automáticos ou integrar mais provedores dependendo do seu caso de uso.