API Reference - Mercado Pago Developers

Recursos para IA

Checkout Pro Checkout Pro redireciona o comprador para um ambiente do Mercado Pago para que conclua o pagamento. Você pode integrá-lo pela API de Orders (fluxo moderno) ou pela API de Preferências (fluxo clássico). Esta referência descreve os endpoints disponíveis e como interagir com eles. Está buscando o passo a passo desta integração? Ir à documentação do Checkout Pro via Orders ou Checkout Pro clássico.

Qual caminho de integração usar? Escolha de acordo com o seu caso de uso.

Via Orders API (Recomendada)

Fluxo simplificado com um único endpoint
checkout_url direto para redirecionar o comprador
Novas funcionalidades e notificações simplificadas

Via Preferências (Legacy)

Fluxo baseado em preferências e init_point
Compatível com integrações existentes

Este caminho de integração não é recomendado. A API de Preferências continuará sendo suportada, mas as novas funcionalidades estarão disponíveis apenas na API de Orders. Se você está começando uma nova integração, use a Orders API. Se você já tem uma integração com Preferências, consulte a documentação do Checkout Pro via Orders para planejar a migração.

Endpoints disponíveis

Todos os endpoints que compõem a integração do Checkout Pro via Preferences.

Preferências

A preferência é o objeto central do fluxo clássico do Checkout Pro. Define os itens, valores, meios de pagamento habilitados e URLs de retorno do comprador.

Operação	Path	Descrição
Criar preferênciaPOST	`/checkout/preferences`	Cria uma preferência com itens, preços e `back_urls`, retornando o `init_point` para redirecionar o comprador.
Pesquisar preferênciasGET	`/checkout/preferences/search`	Pesquisa preferências por filtros como `external_reference` ou data, retornando resultados paginados.
Obter preferênciaGET	`/checkout/preferences/{id}`	Retorna o detalhe de uma preferência: `init_point`, itens e `back_urls` configuradas.
Atualizar preferênciaPUT	`/checkout/preferences/{id}`	Atualiza uma preferência existente antes de o comprador concluir o pagamento.

Pagamentos

Endpoints de leitura para verificar o estado de um pagamento após receber a notificação webhook ou o redirect de retorno.

Operação	Path	Descrição
Pesquisar pagamentosGET	`/v1/payments/search`	Pesquisa pagamentos por filtros como `external_reference`, status ou data, retornando resultados paginados.
Obter pagamentoGET	`/v1/payments/{id}`	Retorna o status e o detalhe do pagamento, incluindo `status_detail`, para confirmar o resultado após a notificação.

Meios de pagamento

Operação	Path	Descrição
Obter meios de pagamentoGET	`/v1/payment_methods`	Lista os meios de pagamento disponíveis para o site, para incluí-los ou excluí-los na preferência.

Contestações

Operação	Path	Descrição
Obter contestaçãoGET	`/v1/chargebacks/{id}`	Busca um caso de contestação a partir de seu ID retornado no body da notificação configurada para contestações. Retorna o detalhe de uma contestação, sendo o status da disputa, o valor afetado e o prazo para definição.
Buscar contestaçõesGET	`/v1/chargebacks/search`	Busca todas as contestações de um pagamento por seu "payment_id" retornado no body da notificação configurada para contestações. A busca retorna resultados paginados com o detalhe de cada caso.
Enviar documentação comprobatóriaPOST	`/v1/chargebacks/{id}/documentation`	Envia arquivos de evidência para contestar uma contestação enquanto seu status ("documentation_status") for "pending".
Obter arquivo de documentação comprobatóriaGET	`/v1/chargebacks/documentation/{type}/{uuid}`	Baixa ou renderiza em linha um arquivo de documentação enviado para um caso de contestação.