Financeiro JurídicoAjuda do Mercado Pago
Voltar às cobranças

CHECKOUT PRO E SERVIÇO PROTEGIDO

Configure as cobranças do Mercado Pago

Este guia mostra como criar a aplicação, proteger o Access Token em um Worker da Cloudflare, conectar o Financeiro Jurídico e validar uma cobrança antes de receber pagamentos reais.

O Access Token nunca vai no navegador

O token é uma credencial privada e deve existir somente como segredo criptografado na Cloudflare. Nunca o coloque no código, no GitHub, no Gist, no campo “Public Key” ou em capturas de tela.

VISÃO GERAL

Por que existe um serviço separado?

O Financeiro Jurídico é uma página estática: ela não possui um servidor privado para guardar senhas. Por isso, o navegador envia apenas os dados necessários da cobrança ao Worker. O Worker adiciona o Access Token protegido e conversa com a API do Mercado Pago.

FinanceiroSolicita a cobrança
Worker protegidoGuarda o token
Mercado PagoCria o Checkout Pro
  • O cliente paga no ambiente seguro do Mercado Pago.
  • O sistema guarda o vínculo entre a cobrança e o lançamento financeiro.
  • Ao atualizar o status, um pagamento aprovado marca o lançamento como realizado.
  • Os primeiros testes usam credenciais e compradores de teste, sem dinheiro real.

O que será necessário

Conta de vendedor

Uma conta Mercado Pago ou Mercado Livre habilitada para receber pagamentos.

Aplicação Checkout Pro

A integração criada em “Suas integrações” no Mercado Pago Developers.

Conta Cloudflare

Uma conta com acesso a Workers para publicar o serviço protegido.

Endereço do sistema

A URL HTTPS em que o Financeiro Jurídico está publicado.

ETAPA 1

Crie a aplicação no Mercado Pago

  1. 1
    Entre no Mercado Pago Developers

    Use a conta que receberá os honorários. Se solicitado, conclua a verificação de identidade ou a reautenticação.

    Abrir “Suas integrações”
  2. 2
    Escolha “Criar aplicação”

    Dê um nome identificável, como “Financeiro OfficeJur”.

  3. 3
    Selecione pagamentos online

    Escolha a categoria de pagamentos online, a opção de Checkouts e a solução Checkout Pro.

  4. 4
    Abra as credenciais de teste

    Dentro da aplicação, acesse Testes → Credenciais de teste. Ative-as caso ainda não tenham sido geradas.

  5. 5
    Identifique as duas credenciais

    A Public Key será informada no Financeiro. O Access Token será cadastrado somente como segredo do Worker.

Referência oficial

O Mercado Pago gera credenciais de teste para validar a integração antes da ativação em produção.

Consultar criação de aplicação

ETAPA 2

Publique o Worker protegido na Cloudflare

O repositório já contém o código necessário. A configuração pode ser feita inteiramente pelo painel da Cloudflare, sem instalar programas no computador.

  1. 1
    Abra o painel da Cloudflare

    Entre na conta do escritório e acesse Workers & Pages.

    Abrir Cloudflare Dashboard
  2. 2
    Crie um Worker

    Escolha criar um Worker, use o nome financeiro-mercado-pago e publique o exemplo inicial.

  3. 3
    Abra o editor de código

    No Worker recém-criado, escolha Edit code ou Quick edit e apague o exemplo.

  4. 4
    Publique o Worker revisado

    Abra o código versionado do serviço, revise os segredos exigidos e publique-o pela Cloudflare.

    Abrir código do Worker
  5. 5
    Salve e publique

    Escolha Save and deploy. Guarde o endereço final, semelhante a https://financeiro-mercado-pago.sua-conta.workers.dev.

Alternativa para desenvolvedores: publicar pelo terminal

Dentro da pasta worker, use Wrangler 4.36.0 ou superior, autentique a conta e cadastre os segredos com npx wrangler secret put MP_ACCESS_TOKEN e npx wrangler secret put OFFICEJUR_API_KEY. Antes de executar npx wrangler deploy, ajuste ALLOWED_ORIGINS e confirme o identificador exclusivo do limitador em wrangler.toml.

ETAPA 3

Cadastre as variáveis e o segredo

No Worker, abra Settings → Variables and Secrets. Adicione os itens abaixo e publique a nova versão quando a Cloudflare solicitar.

ALLOWED_ORIGINS — texto normalInforme somente a origem do sistema, sem caminho e sem barra final. Exemplo: https://seu-dominio.example. Para várias origens, separe por vírgula.
MP_ACCESS_TOKEN — tipo SecretCole o Access Token do ambiente que será usado. Selecione explicitamente o tipo segredo para que o valor fique oculto no painel.
MP_WEBHOOK_URL — opcionalReservado para notificações automáticas. Não é necessário para criar links nem para consultar pagamentos pelo botão de atualização.
Origem não é o endereço completo

Use apenas https://seu-dominio.example em ALLOWED_ORIGINS, sem o caminho da aplicação.

Teste a saúde do serviço

Abra o endereço do Worker acrescentando /health. Com o segredo configurado corretamente, a resposta será {"ok":true}. Se aparecer “MP_ACCESS_TOKEN não configurado”, revise o nome e o ambiente do segredo.

Documentação da Cloudflare

Segredos são apropriados para chaves e tokens porque o valor deixa de ser exibido no painel depois de cadastrado.

Consultar documentação de Secrets

ETAPA 4

Configure o Financeiro Jurídico

  1. 1
    Abra Cobranças

    No menu lateral, escolha “Cobranças” e clique em Configurar conta.

  2. 2
    Comece no ambiente de testes

    Selecione “Testes” e informe a Public Key de teste da aplicação.

  3. 3
    Informe a URL do serviço seguro

    Cole o endereço do Worker sem /health e sem caminhos adicionais.

  4. 4
    Configure o retorno

    Use o endereço completo publicado do Financeiro Jurídico. É para essa página que o cliente retornará depois do Checkout Pro.

  5. 5
    Defina a identificação no extrato

    Use um nome reconhecível, em letras latinas, com no máximo 22 caracteres, como OFFICEJUR.

  6. 6
    Salve a configuração

    O painel não possui campo para Access Token. Isso é intencional: a credencial privada permanece somente na Cloudflare.

AmbienteDefine se o sistema usa o link sandbox ou o checkout real.
Public KeyIdentificação pública da aplicação correspondente ao ambiente.
URL do serviço seguroEndereço publicado do Worker que contém o Access Token protegido.
URL de retornoEndereço HTTPS para o qual o comprador retorna após o pagamento.

ETAPA 5

Gere e valide a primeira cobrança

  1. 1
    Prepare um lançamento

    Cadastre um cliente com nome e e-mail. Crie uma receita vinculada ao cliente e mantenha o status como pendente.

  2. 2
    Crie o link de pagamento

    Em Cobranças, escolha “Gerar cobrança”, selecione o lançamento e confira valor, vencimento, descrição e pagador.

  3. 3
    Use um comprador de teste

    No Mercado Pago Developers, abra Contas de teste → Comprador. Faça o teste em uma janela anônima e nunca use um cartão real com credenciais de teste.

    Consultar teste de integração
  4. 4
    Simule o resultado

    Conclua a compra com os dados de teste indicados pelo Mercado Pago.

  5. 5
    Atualize o status

    Volte à tabela de cobranças e use o ícone de atualização. Quando o pagamento estiver aprovado, o lançamento será marcado como realizado e receberá a forma “Mercado Pago”.

ETAPA 6

Ative pagamentos reais

Só avance depois de concluir os testes

Teste criação do link, retorno ao sistema e atualização de pagamento. Credenciais de teste e produção não podem ser misturadas.

  1. 1
    Ative as credenciais de produção

    Na aplicação do Mercado Pago, abra Produção → Credenciais de produção, complete os dados solicitados e ative as credenciais.

  2. 2
    Troque o segredo na Cloudflare

    Substitua MP_ACCESS_TOKEN pelo Access Token de produção e publique a alteração.

  3. 3
    Troque a configuração do Financeiro

    Selecione “Produção” e substitua a Public Key pela credencial produtiva da mesma aplicação.

  4. 4
    Faça uma validação controlada

    Gere uma cobrança real de pequeno valor, confirme o recebimento e valide o lançamento antes de disponibilizar o fluxo aos clientes.

HTTPS obrigatório

O endereço de produção do sistema e o Worker devem utilizar HTTPS. O GitHub Pages e o domínio workers.dev já fornecem conexão segura.

Consultar requisitos de produção

SOLUÇÃO DE PROBLEMAS

Mensagens e correções mais comuns

“Failed to fetch” ou erro de CORS
Confira a URL do Worker e a variável ALLOWED_ORIGINS. Informe apenas a origem do sistema, sem o caminho /financeiro e sem barra no final. Depois, publique novamente o Worker.
“MP_ACCESS_TOKEN não configurado”
O segredo precisa se chamar exatamente MP_ACCESS_TOKEN, estar no mesmo Worker e no ambiente publicado. Confirme que o tipo escolhido foi Secret e que a implantação foi concluída.
Erro 401, “Unauthorized” ou credencial inválida
O Access Token pode estar incorreto, revogado ou ser de outro ambiente. Troque o segredo na Cloudflare e confirme que a Public Key informada no Financeiro pertence à mesma aplicação e ao mesmo ambiente.
O link continua abrindo o ambiente de testes
No Financeiro, altere o ambiente para Produção. Na Cloudflare, confirme que MP_ACCESS_TOKEN contém o token produtivo. Salve ambas as configurações.
A cobrança foi paga, mas continua pendente
Use o botão de atualizar status. Confirme que o pagamento foi realizado no mesmo ambiente da cobrança e que a referência externa existe no Mercado Pago. A confirmação atual é consultada pelo sistema; o webhook é opcional.
O retorno após o pagamento está incorreto
Revise a “URL de retorno” no Financeiro. Ela deve conter o endereço HTTPS completo do sistema, incluindo o caminho do projeto quando existir.
Como atualizar o Worker no futuro?
Abra worker/src/index.js neste repositório, copie o conteúdo atualizado, substitua o código no editor da Cloudflare e escolha “Save and deploy”. Variáveis e segredos normalmente permanecem cadastrados.

Regras de segurança

  • Nunca coloque o Access Token no código, Gist, Public Key ou configuração visível do navegador.
  • Restrinja o acesso às contas do Mercado Pago e da Cloudflare e ative autenticação em dois fatores.
  • Revogue e substitua imediatamente qualquer credencial que tenha sido exposta.
  • Valide mudanças em ambiente de testes antes de alterar a integração produtiva.