Documentação da API

Três passos: crie sua conta, conecte seu Mercado Pago no painel /conta e chame os endpoints abaixo a partir do seu backend. A API key fica visível no seu painel depois de logar.

Autenticação

Envie sua API key no header Authorization, no formato Bearer. Nunca exponha a chave no front-end — todas as chamadas devem partir do seu servidor.

# exemplo Authorization: Bearer m2pay_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/checkout

Cria uma cobrança e devolve um link de pagamento hospedado pelo Mercado Pago (aceita PIX, cartão e boleto). Redirecione seu cliente pra checkout_url.

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`amount`	number	sim	Valor em reais, ex.: `49.90`. Mínimo R$ 1,00.
`description`	string	não	Aparece na página de pagamento.
`external_reference`	string	não	Um id seu (pedido, fatura) devolvido depois no webhook.
`payer_email`	string	não	Pré-preenche o e-mail do pagador.
`success_url`	string	não	Pra onde o cliente volta após pagar. Padrão: página de sucesso do M2Pay.
`failure_url`	string	não	Pra onde o cliente volta se o pagamento falhar.

# requisição curl -X POST https://m2pay.techm2it.com.br/api/checkout \ -H "Authorization: Bearer m2pay_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "amount": 49.90, "description": "Pedido #1042", "external_reference": "pedido-1042" }' # resposta 201 { "id": "chk_a1b2c3d4e5f6g7h8i9j0", "status": "pending", "amount": 49.90, "fee": 1.88, "checkout_url": "https://www.mercadopago.com.br/checkout/v1/redirect?...", "external_reference": "pedido-1042" }

GET/api/checkout/:id

Consulta pública do status de um checkout (não precisa de API key — o id já é aleatório o bastante). Útil pra sua página de sucesso fazer polling direto do navegador.

# resposta 200 { "id": "chk_a1b2c3d4e5f6g7h8i9j0", "status": "approved", "amount": 49.90, "description": "Pedido #1042", "external_reference": "pedido-1042", "created": 1754857200000, "updated": 1754857260000 }

status pode ser pending, approved, rejected ou in_process.

Webhook

Configure a URL do seu backend no painel /conta. Sempre que um checkout muda de status, o M2Pay envia:

# POST pro seu webhookUrl Content-Type: application/json x-m2pay-signature: <hmac-sha256 hex> { "id": "chk_a1b2c3d4e5f6g7h8i9j0", "status": "approved", "amount": 49.90, "fee": 1.88, "external_reference": "pedido-1042", "description": "Pedido #1042", "updated": 1754857260000 }

A assinatura é um HMAC-SHA256 do corpo da requisição (bytes exatos, antes de qualquer parse) usando o webhook secret da sua conta. Valide antes de confiar no payload:

// Node.js const crypto = require('crypto'); function valido(corpoBruto, assinaturaRecebida, webhookSecret) { const esperado = crypto.createHmac('sha256', webhookSecret).update(corpoBruto).digest('hex'); return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(assinaturaRecebida)); }

Seu webhook secret fica disponível no painel /conta, junto da API key.

Erros

Status	Quando acontece
401	API key ausente ou inválida.
403	Conta suspensa.
409	Conta ainda não conectou o Mercado Pago (painel /conta).
400	Corpo da requisição inválido ou `amount` ausente/abaixo do mínimo.
502	Falha ao criar a cobrança no Mercado Pago — tente de novo.