Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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
  • 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
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
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ó).
CampoO que colocarPara que serve
Salvar resultado comocheckout_responseSalva a resposta da ferramenta (JSON) na Memória com esse nome
Tipo de pagamentopaymentTipo de operação (na maioria dos casos, deixe o padrão)
AmbienteDEV / PRODDefine se você está testando ou cobrando real
Expiração do botão (min)20 (exemplo)Tempo máximo para pagar antes de o link/botão expirar
MoedaCLP, MXN, COP, etc.Moeda da cobrança
Motivo do pagamentotexto ou variávelDescrição legível da cobrança (vista pelo usuário / painel)
Valor tributávellíquido (ex.: mp_net_amount)Base de cálculo de imposto (se IVA/impostos se aplicarem)
Valor isento0 ou valorA parte da cobrança isenta/não sujeita a impostos
Percentual de IVA19 (exemplo)Percentual de imposto (se aplicável)
Metadados do pagamentoopcionalContexto para rastreabilidade (apenas o essencial)
Email do compradorobrigatórioEmail do comprador. Em DEV deve ser um usuário de teste
Personalizar texto do botão de pagamentoNão / SimPermite personalizar a mensagem que acompanha o botão de pagamento (Header/Body/Footer)

​
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

​
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

​
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

SaídaO que significaO que conectar
Entrega correta de CTAO botão foi enviado com sucessoAgente de IA de suporte pós-CTA
Pagamento bem-sucedidoO pagamento foi aprovadoCódigo (normalização) → Texto (recibo)
Pagamento pendenteO pagamento está em processoTexto informativo + acompanhamento
Pagamento falhouO pagamento foi rejeitadoTexto + opção de nova tentativa
Código de erroErro no seu fluxoBloco de tratamento de erros
Erro HttpErro na solicitaçãoBloco de tratamento de erros

​
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

​
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. 
Você é "Suporte de Pagamento", um assistente para concluir pagamentos pelo WhatsApp.

Contexto: o usuário acaba de receber um botão (CTA) para pagar. Seu papel NÃO é vender ou recalcular valores: apenas ajudar a concluir o pagamento ou resolver problemas com o botão.

────────────────────
COMPORTAMENTO PRINCIPAL
────────────────────
- Este agente pode ser executado sem que o usuário tenha escrito nada.
- Se NÃO houver pergunta ou problema explícito do usuário na última mensagem, envie APENAS esta mensagem proativa (uma vez) e então fique em modo reativo:

"Se você tiver alguma dúvida sobre seu pagamento, escreva aqui e eu te ajudo."

- Se o usuário ESCREVER (pergunta/problema), responda diretamente, de forma breve e clara.
- Não reinicie a venda. Não recalcule valores. Não gere novos links. Não invente informações.
- Máximo 1 emoji por mensagem.

────────────────────
O QUE VOCÊ SUPORTA
────────────────────
- Como pagar pelo botão.
- O botão não abre / erro de carregamento.
- Pagamento pendente.
- Pagamento rejeitado.
- Problemas com cartão / método de pagamento.

Se o usuário reportar um problema:
1) Peça uma breve descrição.
2) Se útil, peça uma captura de tela (eles podem enviar imagens).
3) Ofereça gerar um ticket de suporte por e-mail. NÃO gere um ticket sem um "sim" explícito.

────────────────────
TICKET POR E-MAIL (FERRAMENTA GMAIL)
────────────────────
Se o usuário confirmar que quer um ticket, use a ferramenta Gmail para enviar um e-mail para: [email protected]

Assunto:
[Ticket de Pagamento] Operação {operation_id se existir} | Ref {order_reference_id se existir}

Corpo:
- E-mail do comprador/pagador
- O que aconteceu (texto do usuário)
- Status mencionado (pendente/rejeitado/erro)
- Data e hora atuais
- IDs úteis se existirem: operation_id / order_id / order_reference_id
- Anexar evidências se o usuário enviou imagens

Em seguida, confirme:
"Pronto. Gerei o ticket e entraremos em contato por e-mail."

────────────────────
ENCERRAMENTO / FIM DA TAREFA
────────────────────
Se o usuário disser que já pagou e não precisa de mais ajuda (por exemplo, "pronto", "obrigado", "era isso"), responda brevemente e encerre:
"Perfeito. Se precisar de mais alguma coisa, estarei aqui."

​
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
// Reads checkout_response (saved in Memory) and maps the minimum to Context
const r = $memory.getJson('checkout_response')
if (!r) throw new Error('checkout_response does not exist in memory.')

const pl = r?.paymentLinkResponse
if (!pl) throw new Error('checkout_response.paymentLinkResponse does not exist (check memory).')

const gw = pl.gateway_response || {}
const md = pl.metadata || gw.metadata || {}

// buyer email = payer email (in the demo they match)
const email = String(gw?.payer?.email || md.email || '')

// Identifiers and reusable data
$context.set('pay_operation_id', String(gw.id || '')) // "Operation number" in Mercado Pago
$context.set('pay_amount', Number(pl.amount || 0))
$context.set('pay_currency', String(pl.currency || 'CLP'))
$context.set('pay_email', email)
$context.set('pay_concept', String(gw.description || md.concept || ''))
$context.set('pay_status', String(gw.status || 'approved'))

// Receipt line (post-payment message)
$context.set(
  'pay_receipt',
  `Done ✅ Payment approved.\n\nMercado Pago operation number: ${String(gw.id || '')}`
)
Se você usar este código, pode imprimir a mensagem ao usuário em um nó de saída Texto colando esta expressão: 
{{$context.pay_receipt}}
Diagrama: saída Pagamento bem-sucedido do nó Jelou Pay conectada ao nó Código, e este ao nó Texto com 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)

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

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.