Hubpay
← Conectar PSPs

Conectar Mercado Pago

⏱ Tempo estimado: 10 minutos

O Mercado Pago usa um Access Token para autenticação.

1

Criar conta no Mercado Pago

  1. Acesse mercadopago.com.br
  2. Crie uma conta (pessoal ou empresarial)
  3. Verifique seu email e identidade
2

Criar aplicação no Mercado Pago Developers

  1. Acesse mercadopago.com.br/developers/panel
  2. Faça login com sua conta Mercado Pago
  3. Clique em Suas integrações → Criar aplicação
  4. Preencha:
    • Nome: "Hubpay" (ou nome do seu projeto)
    • Marque que vai processar pagamentos
  5. Clique em Criar aplicação
3

Obter Access Token

Para testes (Sandbox)

  1. Na aplicação criada, vá em Credenciais de teste
  2. Copie o Access Token de teste
  3. O token começa com TEST-

Para produção

  1. Na aplicação criada, vá em Credenciais de produção
  2. Copie o Access Token de produção
  3. O token começa com APP_USR-
⚠️O Mercado Pago usa a mesma URL de API para sandbox e produção — o que diferencia é o token. Guarde o token em lugar seguro.
4

Conectar no Hubpay

  1. Acesse hubpay.dev/dashboard/psps
  2. Clique em Conectar novo PSP
  3. Selecione Mercado Pago
  4. Selecione o ambiente:
    • Test se está usando token de teste (TEST-...)
    • Live se está usando token de produção (APP_USR-...)
  5. Dê um label (ex: "MP principal")
  6. Cole o Access Token
  7. Clique em Salvar credencial
5

Testar

bash
curl -X POST https://api.hubpay.dev/v1/charges \
  -H "Authorization: Bearer hpx_test_SUA_CHAVE_HUBPAY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "provider": "mercadopago",
    "description": "Teste MP",
    "payer": {
      "email": "comprador@example.com"
    }
  }'
💡O Mercado Pago exige email do pagador. Se não enviar, o Hubpay usa um email padrão, mas recomendamos sempre informar para evitar problemas.
6

Configurar webhook (recomendado)

Após salvar a credencial, o Hubpay gera uma URL de webhook única pra ela. Cole essa URL no painel do Mercado Pago pra receber notificações de pagamento em tempo real. Formato:

text
https://api.hubpay.dev/api/wh/{uuid}
  1. Em /dashboard/psps, no menu "..." da credencial, clique em Copiar URL do webhook.
  2. No painel de devs, abra a aplicação → Webhooks → Configurar notificações.
  3. Modo: Sua aplicação. Cole a URL no campo URL.
  4. Marque o evento Pagamentos (Payments).
  5. Salve.
💡O MP não inclui o status do pagamento no webhook — o Hubpay consulta o status via API usando a credencial salva. Por isso a validação aqui é por ownership da cobrança no banco, não por header de token.

Solução de problemas

ErroCausaSolução
502 com "unauthorized"Access Token inválidoVerifique se copiou corretamente, sem espaços extras
502 com "invalid payer email"Email do pagador inválidoEnvie um email válido no campo payer.email
Cobrança criada mas Pix não apareceConta MP sem Pix habilitadoAtive o Pix no painel do Mercado Pago

Links úteis