Primeiros passos com a Reval: instale e configure a sua loja
Instale a Reval na sua loja Shopify, conecte o Mercado Pago e crie o seu primeiro plano de assinatura recorrente em menos de 15 minutos.
A Reval é instalada diretamente no seu admin da Shopify e não exige modificar código nem contratar infraestrutura adicional. Siga este guia passo a passo para deixar a sua loja pronta para vender assinaturas recorrentes cobradas pelo Mercado Pago.O dashboard da Reval acompanha você: enquanto faltar configuração, você verá o cartão “Primeiros passos” com o status real de cada ponto (credenciais salvas, webhook verificado, primeiro plano criado) e um atalho para este guia. Ele desaparece sozinho quando tudo estiver pronto.
A Reval solicita as seguintes permissões na sua loja Shopify no momento da instalação:
Leitura: pedidos, produtos, impostos, valores de frete e dados de clientes.
Escrita: criação e atualização de pedidos recorrentes.
Essas permissões são estritamente necessárias para gerar as cobranças automáticas e calcular frete e impostos em tempo real durante o checkout.
1
Instale o app com o seu link de instalação
A Reval é um app de distribuição customizada: não está publicada na Shopify App Store. Você vai receber um link de instalação gerado especificamente para a sua loja.Abra-o com a sessão de proprietário da loja e aceite as permissões. Uma vez instalada, a Reval aparece em Apps dentro do seu admin, embutida — não há nenhum site externo para acessar.
O link está vinculado ao domínio da sua loja e só serve para ela.
2
Informe as suas credenciais do Mercado Pago
A Reval precisa de acesso à sua conta do Mercado Pago para criar os mandatos de cobrança recorrente e receber a notificação de cada cobrança.Não há conexão por OAuth: as credenciais são copiadas do painel do MP e coladas na Reval, onde ficam salvas de forma criptografada para a sua loja.
Tudo o que segue é feito no painel de desenvolvedores do Mercado Pago, dentro da sua aplicação. Se você ainda não a criou, o passo 2.0 orienta; se já tem, pule direto para o 2.1.
Crie uma aplicação nova e dedicada à Reval. Não reutilize a que você usa para cobrar no seu checkout.Por dois motivos:
Cada aplicação é criada para um produto do Mercado Pago. Uma aplicação de checkout não habilita as APIs de Assinaturas, que são as que a Reval precisa para as cobranças recorrentes.
Cada aplicação admite uma única URL de webhook por modo. Se você colar a URL da Reval em uma aplicação que já tem um webhook configurado, você o sobrescreve — e as notificações do seu checkout deixam de chegar onde chegavam, sem nenhum aviso.
Ter duas aplicações não separa o seu dinheiro nem as suas contas: ambas pertencem à mesma conta do Mercado Pago e tudo é creditado no mesmo lugar. Uma aplicação é uma credencial de integração, não uma carteira. Não tem custo nem limite.
Se você vende com o Mercado Pago mas nunca entrou no painel de desenvolvedores, provavelmente não tem nenhuma aplicação própria: a integração de pagamentos da Shopify é vinculada pelo admin da loja, sem passar por lá. Nesse caso, basta criar a primeira.
Acesse o painel de desenvolvedores do Mercado Pago com a conta do MP que vai cobrar as assinaturas. No canto superior direito, abra Integrações: você verá a lista Suas aplicações.
As capturas de tela desta página foram feitas em um painel do Mercado Pago em espanhol. No painel brasileiro os rótulos aparecem em português — indicamos os dois: o texto em português primeiro e, entre parênteses, o que você vê na imagem.
Lista de aplicações no painel de desenvolvedores
Clique em Criar aplicação (Crear aplicación).
Nome da aplicação (Nombre de la aplicación — passo 1 de 4): um nome descritivo, por exemplo o da sua loja. Até 50 caracteres. Continuar.
Passo 1 de 4 — nome da aplicação
Tipo de pagamento (passo 2 de 4): escolha Pagamentos on-line (Pagos online).
Passo 2 de 4 — escolha Pagamentos on-line
Ao selecioná-lo aparece a pergunta “Como você fez a loja?” (¿Cómo hiciste la tienda?): escolha Com um desenvolvimento próprio (Con un desarrollo propio). A URL da loja é opcional — você pode informar o domínio da sua loja ou deixá-la vazia. Continuar.
Passo 2 de 4 — com um desenvolvimento próprio
Mesmo que a sua loja esteja na Shopify, a opção correta é Com um desenvolvimento próprio — o checkout de assinaturas da Reval é próprio, não o de uma plataforma.
Solução de cobrança (passo 3 de 4): na aba Checkouts, escolha Checkout API (a de “integração avançada” — é a única das três que combina pagamentos dentro da sua loja com pagamentos recorrentes). Se perguntar qual tipo de Checkout API, escolha API de Pagamentos (API de Pagos). Continuar.
Passo 3 de 4 — Checkout API
Confirme (passo 4 de 4): revise o resumo (Pagamentos on-line · Com um desenvolvimento próprio · Checkout API · API de Pagamentos), marque a autorização de dados pessoais, resolva o captcha e clique em Confirmar.
Passo 4 de 4 — confirmação
Com a aplicação criada, entre nela por Suas aplicações e siga para o passo 2.1.
No menu lateral, entre em NOTIFICAÇÕES → Webhooks (NOTIFICACIONES → Webhooks). Confirme que você está na aba Modo produtivo e não em “Modo de teste”: são duas configurações independentes e a de teste não é usada.
Configuração de webhooks em modo produtivo
Em URL de produção, cole a URL de notificações (webhook) que a Reval mostra em Configuração → Integrações — Mercado Pago (há um botão Copiar URL ao lado). A URL já vem montada com a sua loja — não é preciso editá-la.
O ?shop= do final não é opcional: é o que indica à Reval de qual loja vem a notificação e com qual chave secreta validá-la. Se você o omitir, o Mercado Pago responde 200 de todo modo e tudo parece funcionar, mas você fica dependendo de um mecanismo de respaldo. Copie a URL completa, exatamente como a Reval a mostra.
Em Eventos recomendados para integrações com Assinaturas, marque exatamente dois:
Planos e assinaturas (Planes y suscripciones)
Pagamentos (legacy) (Pagos (legacy))
Não marque nenhum outro. Os eventos a mais não quebram nada, mas geram tráfego que a Reval descarta.
Copie a Chave secreta que aparece no final da tela. Esse é o terceiro valor que você vai colar na Reval.
Clique em Salvar configuração.
O botão de atualizar que fica ao lado da chave secreta gera uma nova e invalida a anterior. Se você clicar nele depois de já ter configurado a Reval, os webhooks começam a falhar na validação de assinatura e as cobranças deixam de gerar pedidos na Shopify. Se isso acontecer, copie a chave nova e atualize-a na Reval.
O nome “Pagamentos (legacy)” parece se referir a algo descontinuado, mas é o evento correto: é o que notifica cada cobrança individual do mandato, e é o que a Reval escuta para criar o pedido na Shopify.
Na Reval, vá em Configuração → Integrações — Mercado Pago e preencha:
Public key (começa com APP_USR)
Access token (começa com APP_USR)
Webhook secret — a chave secreta do passo anterior
Salve.
O access token e o webhook secret não voltam a ser exibidos depois de salvos: os campos ficam mascarados. É o comportamento esperado. Se precisar trocá-los, escreva o valor novo em cima e salve de novo.
Clique em Testar conexão. O teste usa as credenciais salvas, então salve antes de testar.Se tudo estiver certo, aparece uma mensagem verde com o nome da sua conta do Mercado Pago e o código do seu país (MLA Argentina, MLB Brasil, MLC Chile, MCO Colômbia, MLM México, MPE Peru, MLU Uruguai).
O que você vê
O que significa
”Conexão OK — sua conta (MLB)“
Pronto, siga para o passo seguinte.
”O Mercado Pago recusou o access token”
O token está incompleto ou é de teste. Copie-o de novo em Credenciais de produção.
Conexão OK mas com outro nome de conta
Pare aqui. Veja o aviso abaixo.
Se o nome que aparece não é o da sua conta, o access token é de outra conta: pare aí. Um token errado não dá erro, simplesmente cobraria na conta incorreta.Considere também que a Reval opera com credenciais produtivas: não há modo sandbox, e os cartões de teste do MP não funcionam. Para validar o fluxo, faz-se uma compra real de valor baixo e depois se estorna.
3
Crie o seu primeiro plano de assinatura
Os planos definem a frequência de cobrança e o desconto que os assinantes recebem em relação ao preço de tabela.
Vá em Planos no menu lateral da Reval e preencha a seção Criar um plano de assinatura.
Preencha os campos:
Nome do plano: por exemplo, “Mensal” ou “Trimestral com desconto”.
Frequência: combine um intervalo numérico com uma unidade de tempo — dias, semanas ou meses. Por exemplo: 1 mês para cobrança mensal, 3 meses para trimestral, 14 dias para quinzenal.
Tipo de desconto: percentual de desconto (entre 1 e 99, sobre o preço de tabela de cada produto) ou preço fixo (o mesmo valor para todos os produtos do plano). Se você não quiser aplicar desconto, use preço fixo com o preço normal do produto.
Desconto extra no 1º pedido (opcional): um percentual adicional que se aplica SOMENTE à primeira cobrança. A partir do segundo ciclo é cobrado o preço normal do plano, e o comprador vê os dois preços antes de assinar.
Selecione os produtos e clique em Criar plano.
O Mercado Pago tem um valor mínimo por cobrança (depende da moeda da sua conta). A Reval não permite salvar planos cujo preço final fique abaixo desse mínimo e mostra o valor exato ao tentar — se você vir esse aviso, aumente o preço ou reduza o desconto.
Você pode criar quantos planos precisar. Os compradores os verão como opções no buy box do produto.
4
Adicione o bloco da Reval ao seu tema
O buy box é o widget que aparece na página do produto e permite ao comprador escolher entre comprar uma única vez ou assinar. Ele é adicionado como um bloco de app pelo editor de temas — sem mexer em código:
Na Shopify: Loja virtual → Temas → Personalizar.
Abra uma página de produto e, na seção de informações do produto, clique em Adicionar bloco → Apps → “Reval”.
Salve. O bloco se acomoda sozinho junto aos botões de compra (quantidade → opções → botão de assinar), onde quer que você o deixe.
Nas configurações do bloco você pode editar os benefícios exibidos ao escolher a assinatura, ativar a pré-seleção da opção de assinar e definir um logo para o checkout. A opção «Mostrar opção de compra avulsa» (ativada por padrão) controla se o buy box oferece a compra sem assinatura: desative-a para vender o produto apenas por assinatura.
Ícone da aba do navegador: no checkout da Reval, o ícone que aparece na aba vem do logo quadrado da sua loja — carregado na Shopify em Configurações → Marca → Logo quadrado (é um ajuste diferente do favicon do tema). Se ele não estiver carregado, a Reval adapta o seu logo principal para um quadrado; fica melhor se você enviar o quadrado — o mesmo arquivo que você usa como favicon do tema serve.
O buy box só aparece em produtos que têm um plano ativo — nos demais o bloco fica invisível, então é seguro adicioná-lo ao template geral de produto.
Preview do buy box com a opção de assinatura ativa
O buy box exige que o tema da sua loja tenha JavaScript habilitado. Se você usa um tema muito personalizado ou com scripts bloqueados, verifique se o widget carrega corretamente antes de publicá-lo.
5
Faça uma assinatura de teste
Antes de anunciar a funcionalidade aos seus clientes, verifique se o fluxo completo funciona de ponta a ponta.Como a Reval opera com credenciais produtivas, o teste é feito com um cartão real e um valor baixo, que você estorna depois. Vale criar um plano temporário barato para isso.
Abra a página do produto onde o buy box aparece em uma janela anônima.
Escolha o plano de teste e finalize o checkout com um cartão real.
Verifique se:
O pedido aparece em Pedidos dentro do admin da Shopify, com as tags Suscripción, Primera compra e Ciclo 1 (as tags são emitidas em espanhol).
A assinatura aparece em Assinaturas dentro da Reval, com status ativo.
O mandato consta no seu painel do Mercado Pago.
Cancele a assinatura de teste e estorne a cobrança pelo painel do MP.
Se você também oferece add-ons, marque um no checkout de teste: verifique se no Mercado Pago aparecem duas cobranças separadas (a do mandato e a do add-on) e se o pedido inclui as duas linhas.
Antes de lançar o seu programa de assinaturas, considere as seguintes restrições atuais da Reval:
Não existe cobrança sob demanda: você não pode iniciar uma cobrança manual fora do ciclo programado. As cobranças são executadas automaticamente pelo Mercado Pago na data programada.
Pular um ciclo existe, mas com data aproximada: é ativado em Configuração → Pedidos e estoque, e por baixo funciona pausando o débito e reativando-o um ciclo depois, então a data da cobrança seguinte é decidida pelo Mercado Pago ao reativar. O detalhe está em Limitações.
Não é possível mudar a data da próxima cobrança: a data do ciclo seguinte é determinada pelo Mercado Pago conforme a frequência do plano e não pode ser antecipada nem postergada manualmente.
Não é possível mudar a frequência de uma assinatura ativa: se um assinante quiser passar de um plano mensal para um trimestral, o único caminho é cancelar a assinatura atual e criar uma nova com o plano desejado.
Não existem cartões de respaldo: cada assinatura está associada a um único meio de pagamento. Se a cobrança falhar, não se tenta com outro meio.
