Como criar módulo conector do Mercado Pago
Introdução
Este artigo detalha como configurar, autenticar e integrar a API do Mercado Pago no Skyone Studio usando a opção de criar módulo.
O que é a API do Mercado Pago?
A API do Mercado Pago utiliza uma arquitetura RESTful para permitir a interação programática com a plataforma de pagamentos. A comunicação é realizada via protocolo HTTPS, com troca de dados padronizada no formato JSON. As operações disponíveis no módulo executam internamente as chamadas às rotas da API, sem a necessidade de interação direta com os endpoints.
Principais capacidades:
Processamento de gagamentos: criação e gestão de pagamentos via cartão de crédito, PIX, boleto e outros meios locais, como o PSE (Colômbia).
Gestão de lojas físicas e QR Code: administração de estrutura de lojas (Stores), caixas (POS) e geração de QR Codes dinâmicos ou estáticos para pagamentos presenciais.
Integração com maquininhas (Point): gestão de dispositivos Point, alteração de modos de operação e criação de intenções de pagamento.
Checkout Pro e Bricks: criação de preferências de pagamento para checkout web e gestão de componentes de UI (Bricks).
Gestão de clientes e cartões: armazenamento seguro de dados de clientes e tokenização de cartões para compras futuras (One-Click).
Conceitos Fundamentais
A estrutura do Mercado Pago divide-se entre o ambiente "Online" (Checkout API/Pro) e o ambiente "Físico" (QR Code/Point).
Estrutura de Dados e Hierarquia
Para manipular dados no Mercado Pago com sucesso, é fundamental compreender como as informações são estruturadas:
Collector (Usuário/Vendedor) Representa a conta do Mercado Pago que recebe os valores. Muitas operações exigem o
userId(ID do coletor) para identificar o proprietário da loja ou do pagamento.Store (Loja Física) & POS (Ponto de Venda) Utilizados principalmente em integrações de QR Code e Maquininhas Point.
Store: Representa o estabelecimento físico (endereço, horário). Identificada por
store_idouexternal_store_id.POS: Representa o caixa ou terminal dentro da loja. Identificado por
pos_idouexternal_pos_id.
Preference (Preferência de Pagamento) Objeto central do Checkout Pro. Contém todas as informações da venda (itens, valores, pagador, URLs de retorno) e gera o link para o qual o comprador é redirecionado.
Payment (Pagamento) O registro financeiro da transação. Possui status (ex:
approved,pending,rejected) e pode ser capturado (em casos de pré-autorização) ou reembolsado.Checkouts Os checkouts são opções de fluxo do Mercado Pago que são escolhidas ao criar a aplicação na plataforma.
Checkout API (Transparente): permite criar pagamentos diretamente via backend utilizando o endpoint /v1/payments. Esta modalidade exige que o integrador manipule dados sensíveis tokenizados, como o card_token_id, e defina explicitamente o método de pagamento, como cartão, boleto ou PIX, no corpo da requisição. Oferece controle total sobre a interface, pois a transação ocorre sem redirecionamento visível para o usuário final. A Checkout API exige verificação da empresa na plataforma do Mercado Pago
Checkout Pro (Redirecionamento): opera através da criação de Preferências (intenção de compra) usando o endpoint /checkout/preferences. Ao criar uma preferência, o integrador envia os detalhes da compra, como itens, valores e pagador, e recebe uma URL para redirecionar o usuário ao ambiente seguro do Mercado Pago. Este modelo gerencia automaticamente a seleção de múltiplos métodos de pagamento, como saldo em conta, cartões e boletos, em uma única interface fornecida pelo Mercado Pago.
Checkout Bricks: aparece como uma camada modular que pode interagir tanto com o modelo de Preferências do Checkout Pro quanto com a criação direta de Pagamentos do Checkout API, permitindo a construção de interfaces modulares pré-fabricadas.
Os endpoints de todos os checkouts estão no template, mas é recomendável remover os inutilizados no fluxo escolhido para evitar confusões.
Pré-requisitos e Configuração no Mercado Pago
Para iniciar o desenvolvimento, são necessários os seguintes elementos do Mercado Pago:
Conta ativa no Mercado Pago: acesso ao Dashboard .
Aplicação Criada: uma aplicação criada na área de "Suas Integrações" para obter as credenciais.
Tipos de Autenticação suportados
A API do Mercado Pago suporta autenticação com OAuth2 e Bearer Token.
Obtendo as Credenciais
Para obter as credenciais, siga os seguintes passos:
Selecione sua aplicação
Navegue até Credenticias de Produção (ou Teste).
Copie o Access Token
Configuração da Conta no Skyone Studio
Para conectar os módulos, é necessário criar a conta de autenticação correta.
Configurando Bearer Token
No Skyone Studio, crie um módulo chamado Mercado Pago.
No módulo do Mercado Pago, clique em Gerenciar contas e, em seguida, em Adicionar conta.
Preencha os campos conforme abaixo:
Nome da Conta
[Defina um nome identificável]
Host
https://api.mercadopago.com
Porta
443
Token
Insira o Access Token (Bearer) obtido no painel.
Salve as alterações e selecione a conta criada no campo "Conta conectada".
5. Operações Disponíveis
Abaixo listamos as operações (endpoints) mapeadas neste conector, organizadas por contexto de uso.
Gestão de QR Code e Lojas (QR Dynamic/Attended & Store/POS)
Estas operações permitem criar infraestrutura para pagamentos presenciais e gerar QR Codes.
QR - Attended-Store & POS Management-Stores-Create Store
POST
Cria loja física para a conta do usuário (múltiplas permitidas).
QR - Attended-Store & POS Management-Stores-Update Store
PUT
Atualiza dados de uma loja física.
QR - Attended-Store & POS Management-Stores-GET Store by ID
GET
Consulta as informações de uma loja física pelo ID.
QR - Attended-Store & POS Management-Stores-Delete Store
DELETE
Exclui a loja física do usuário identificado pelo ID.
QR - Attended-Store & POS Management-Stores-Search Store by External_ID
GET
Busca loja pelo ID externo.
QR- Dynamic-Store & POS Management-Stores-Create Store
POST
Cria uma loja física para o usuário.
QR- Dynamic-Store & POS Management-Stores-Update Store
PUT
Atualiza as informações de uma loja física.
QR- Dynamic-Store & POS Management-Stores-GET Store by ID
GET
Obtém todas as informações de uma loja física a partir do seu ID.
QR- Dynamic-Store & POS Management-Stores-Delete Store
DELETE
Exclui a loja do usuário.
QR- Dynamic-Store & POS Management-Stores-Search Store by External_ID
GET
Busca as informações da loja pelo External_ID.
QR - Attended-Store & POS Management-POS-Create POS
POST
Cria um ponto de venda com QR Code único.
QR - Attended-Store & POS Management-POS-Update POS
PUT
Atualiza os dados de um ponto de venda identificando por ID.
QR - Attended-Store & POS Management-POS-GET POS by ID
GET
Retorna todas as informações de um ponto de venda pelo ID.
QR - Attended-Store & POS Management-POS-DELETE POS
DELETE
Exclui um ponto de venda pelo ID.
QR - Attended-Store & POS Management-POS-Search POS by External POS ID
GET
Busca informações do POS pelo ID externo.
QR- Dynamic-Store & POS Management-POS-Create POS
POST
Cria um ponto de venda com QR Code exclusivo.
QR- Dynamic-Store & POS Management-POS-Update POS
PUT
Atualiza dados do ponto de venda.
QR- Dynamic-Store & POS Management-POS-GET POS by ID
GET
Consulta todas as informações de um ponto de venda pelo ID.
QR- Dynamic-Store & POS Management-POS-DELETE POS
DELETE
Remove ponto de venda pelo ID.
QR- Dynamic-Store & POS Management-POS-Search POS by External POS ID
GET
Busca o POS pelo ID externo do ponto de venda.
QR- Dynamic-Orders-Create Dinamic QR
POST
Cria QR dinâmico do ponto de venda de um colecionador.
QR- Dynamic-Orders-Create order to static QR
PUT
Cria pedido de pagamento por QR estático no POS do coletor.
QR - Attended-Orders-Create Order
PUT
Cria ordem de pagamento para produto/serviço e vincula ao ponto de venda.
QR - Attended-Orders-GET Order by External POS ID
GET
Consulta pedido por ID externo do POS.
QR - Attended-Orders-Delete Order by External POS ID
DELETE
Deleta ordem com ID do usuário e ID externo do POS.
Integração Point (Maquininhas)
Operações focadas na gestão de dispositivos físicos Point e suas transações.
Point-Devices-Get paged devices list
GET
Lista dispositivos, podendo filtrar por ID do ponto de venda e/ou loja.
Point-Devices-Change operating mode
PATCH
Altera o modo de operação do dispositivo para PDV ou STANDALONE.
Point-Transaction Intents-Create payment intent
POST
Cria intenção de pagamento para um dispositivo.
Point-Transaction Intents-Find information payment intent
GET
Recupera informações e status final de uma intenção de pagamento.
Point-Transaction Intents-Cancel payment intent
DELETE
Cancela a intenção de pagamento de um dispositivo.
Point-Store & POS Management-Stores-Create Store
POST
Cria loja física para vendas presenciais.
Point-Store & POS Management-Stores-Update Store
PUT
Atualiza os dados de uma loja física.
Point-Store & POS Management-Stores-GET Store by ID
GET
Ver informações detalhadas de uma loja física pelo ID.
Point-Store & POS Management-Stores-Delete Store
DELETE
Deleta uma loja física identificada pelo ID.
Point-Store & POS Management-Stores-Search Store by External_ID
GET
Busca as informações da loja pelo ID externo associado ao usuário.
Point-Store & POS Management-POS-Create POS
POST
Cria um ponto de venda na loja, gerando um QR code único.
Point-Store & POS Management-POS-Update POS
PUT
Atualiza informações de um ponto de venda.
Point-Store & POS Management-POS-GET POS by ID
GET
Consulta informações de um ponto de venda pelo seu ID.
Point-Store & POS Management-POS-DELETE POS
DELETE
Apaga o POS pelo ID.
Point-Store & POS Management-POS-Search POS by External POS ID
GET
Busca POS pelo ID externo do POS.
Point-Payments & Refunds-Refund Payment (Total)
POST
Reembolsa integralmente um pagamento.
Point-Payments & Refunds-Refund Payment (Partial)
POST
Processa reembolso parcial de um pagamento.
Point-Payments & Refunds-Get Payment by ID
GET
Consulta detalhes de um pagamento pelo ID.
Point-Payments & Refunds-Get Payment by External Reference
GET
Consulta pagamento por referência externa.
Pagamentos e Reembolsos (Geral)
Operações para consulta, estorno e gestão de pagamentos realizados.
QR - Attended-Payments & Refunds-Get Payment by ID
GET
Consulta as informações de um pagamento pelo ID.
QR - Attended-Payments & Refunds-Get Payment by External Reference
GET
Consulta pagamento pelo código de referência externo.
QR - Attended-Payments & Refunds-Refund Payment (Total)
POST
Realiza reembolso total de um pagamento específico.
QR - Attended-Payments & Refunds-Refund Payment (Partial)
POST
Reembolsa parcialmente um pagamento específico.
QR- Dynamic-Payments & Refunds-Get Payment by ID
GET
Retorna todas as informações de um pagamento pelo ID.
QR- Dynamic-Payments & Refunds-Get Payment by External Reference
GET
Consulta pagamento pelo número de referência externo.
QR- Dynamic-Payments & Refunds-Refund Payment (Total)
POST
Refundo totalmente o pagamento identificado.
QR- Dynamic-Payments & Refunds-Refund Payment (Partial)
POST
Reembolsar parcialmente um pagamento.
Merchant Orders (Pedidos)
Gestão de pedidos que agrupam pagamentos e itens.
QR - Attended-Merchant Orders-GET Merchant Order by ID
GET
Consulta informações de pagamento de pedido pelo ID.
QR - Attended-Merchant Orders-GET Merchant Order by External Reference
GET
Busca as informações do pedido de merchant pela referência externa.
QR- Dynamic-Merchant Orders-GET Merchant Order by ID
GET
Consulta as informações de pagamento de um pedido de comerciante pelo ID.
QR- Dynamic-Merchant Orders-GET Merchant Order by External Reference
GET
Consulta todas as informações do pedido do comerciante por referência externa.
Checkout Pro-Merchant Orders-Get Merchant Order
GET
Consulta informações de pagamento e status do pedido pelo ID.
Checkout Bricks-Mercado Pago Account (Checkout Pro)-Merchant Orders-Get Merchant Order
GET
Consulta informações de pagamento e status de uma ordem de comerciante.
Checkout API e Bricks (Pagamentos Online)
Criação direta de pagamentos (Cartão, PIX, Boleto) e gestão de preferências de checkout.
Checkout API-Payments-Create Payment (card)
POST
Cria um pagamento com cartão, incluindo itens e pagador.
Checkout API-Payments-Create Payment - Tourism (card)
POST
Cria pagamento com dados completos de turismo.
Checkout API-Payments-Create Payment - Tickets and Entertainment (card)
POST
Cria pagamento com cartão incluindo detalhes de evento.
Checkout API-Payments-[Brasil] Create Payment (PIX)
POST
Cria pagamento via PIX (Brasil).
Checkout API-Payments-[Brasil] Create Payment (boleto)
POST
Cria pagamento com boleto (Brasil).
Checkout API-Payments-[Colombia] Create Payment (PSE Avanza)
POST
Cria pagamento com PSE Avanza na Colômbia.
Checkout API-Payments (auth + capture)-Create Payment (card)
POST
Cria pagamento autorizado com cartão, aguardando captura.
Checkout API-Payments (auth + capture)-Capture Payment (Total)
PUT
Captura o valor total de pagamento pré‑autorizado.
Checkout API-Payments (auth + capture)-Capture Payment (Partial)
PUT
Captura parcial de pagamento pré-autorizado.
Checkout API-Payments (auth + capture)-Cancel Pre Authorization
PUT
Cancela pagamento pré‑autorizado.
Checkout API-Payments-Get Payment by ID
GET
Consulta todas as informações de um pagamento pelo ID.
Checkout API-Payments-Get Payment by External Reference
GET
Recupera pagamento usando referência externa.
Checkout Bricks-Payments-Create Payment (card)
POST
Criar pagamento com cartão.
Checkout Bricks-Payments-Create Payment - Tourism (card)
POST
Cria pagamento com dados completos de turismo.
Checkout Bricks-Payments-Create Payment - Tickets and Entertainment (card)
POST
Cria pagamento de cartão para itens de entretenimento.
Checkout Bricks-Payments-[Brasil] Create Payment (PIX)
POST
Cria pagamento via PIX (Brasil apenas).
Checkout Bricks-Payments-[Brasil] Create Payment (boleto)
POST
Cria pagamento com boleto no Brasil.
Checkout Bricks-Payments (auth + capture)-Create Payment (card)
POST
Cria pagamento autorizado via cartão, com captura posterior.
Checkout Bricks-Payments (auth + capture)-Capture Payment (Total)
PUT
Captura o valor total de um pagamento pré‑autorizado.
Checkout Bricks-Payments (auth + capture)-Capture Payment (Partial)
PUT
Captura parcialmente um pagamento pré-autorizado.
Checkout Bricks-Payments (auth + capture)-Cancel Pre Authorization
PUT
Cancelar pagamento pré‑autorizado.
Checkout Bricks-Payments-Get Payment by ID
GET
Consulta detalhes do pagamento pelo ID.
Checkout Bricks-Payments-Get Payment by External Reference
GET
Busca todas as informações de um pagamento usando sua referência externa.
Preferências de Checkout (Checkout Pro)
Checkout Pro-Preferences-Create Preference
POST
Cria preferência de pagamento e retorna URL de checkout.
Checkout Pro-Preferences-Create Preference - Tourism
POST
Cria preferência de pagamento para turismo.
Checkout Pro-Preferences-Create Preference - Tickets and Entertainment
POST
Criar preferência de pagamento – Ingressos e Entretenimento.
Checkout Pro-Preferences-Update Preference
PUT
Atualização de detalhes da preferência de pagamento.
Checkout Pro-Preferences-Get Preference
GET
Obtém informações detalhadas de uma preferência específica.
Checkout Pro-Marketplace model-Create Preference - Marketplace Fee
POST
Cria preferência de checkout com taxa de marketplace.
Checkout Bricks-Mercado Pago Account (Checkout Pro)-Preferences-Create Preference
POST
Cria uma preferência de pagamento.
Checkout Bricks-Mercado Pago Account (Checkout Pro)-Preferences-Update Preference
PUT
Atualiza os detalhes de uma preferência de pagamento.
Checkout Bricks-Mercado Pago Account (Checkout Pro)-Preferences-Get Preference
GET
Consulta preferência de checkout pelo ID.
Checkout Bricks-Marketplace model-Create Preference - Marketplace Fee
POST
Cria preferência de checkout adicionando taxa de marketplace.
Clientes e Cartões (Customers & Cards)
Checkout API-Customers & Cards-Customers-Create Customer
POST
Cria cliente com todos os dados e registra cartões.
Checkout API-Customers & Cards-Customers-Update Customer
PUT
Atualiza os dados de um cliente.
Checkout API-Customers & Cards-Customers-Get Customer
GET
Busca informações do cliente pelo ID.
Checkout API-Customers & Cards-Customers-Get Customer by Email
GET
Busca informações do cliente usando o e‑mail.
Checkout API-Customers & Cards-Cards-Add Credit Card
POST
Registra o cartão de crédito do cliente no sistema.
Checkout API-Customers & Cards-Cards-Update Customer Card
PUT
Atualiza detalhes de cartão de cliente.
Checkout API-Customers & Cards-Cards-Get Customer Card
GET
Consulta a referência de um cartão salvo de um cliente.
Checkout API-Customers & Cards-Cards-Get All Customer Cards
GET
Consulta cartões salvos do cliente.
Checkout API-Customers & Cards-Cards-Delete Customer Card
DELETE
Remove cartão de cliente.
Checkout API-Customers & Cards-Payments-Create Payment existing customer(card)
POST
Cria pagamento com cartão para cliente já existente.
Checkout API-Customers & Cards-Zero Dollar Auth-Card Validation (with customer id)
POST
Valida cartão de cliente já cadastrado com transação zero.
Checkout API-Customers & Cards-Zero Dollar Auth-Card validation (with email)
POST
Valida cartão com transação zero e e-mail do pagador.
Checkout Bricks-Customers & Cards-Customers-Create Customer
POST
Cria cliente com dados completos.
Checkout Bricks-Customers & Cards-Customers-Update Customer
PUT
Atualiza dados de um cliente.
Checkout Bricks-Customers & Cards-Customers-Get Customer
GET
Exibe os dados de um cliente pelo ID.
Checkout Bricks-Customers & Cards-Customers-Get Customer by Email
GET
Busca cliente por e‑mail.
Checkout Bricks-Customers & Cards-Cards-Add Credit Card
POST
Armazena referência de cartão de crédito do cliente.
Checkout Bricks-Customers & Cards-Cards-Update Customer Card
PUT
Atualiza os dados de um cartão de cliente.
Checkout Bricks-Customers & Cards-Cards-Get Customer Card
GET
Verifica os dados de um cartão salvo para um cliente.
Checkout Bricks-Customers & Cards-Cards-Get All Customer Cards
GET
Lista cartões armazenados de um cliente.
Checkout Bricks-Customers & Cards-Cards-Delete Customer Card
DELETE
Remove cartão de um cliente.
Checkout Bricks-Customers & Cards-Payments-Create Payment existing customer(card)
POST
Cria pagamento de cliente já salvo utilizando cartão.
Checkout Bricks-Customers & Cards-Zero Dollar Auth-Card Validation (with customer id)
POST
Valida cartão do cliente mediante transação zero.
Checkout Bricks-Customers & Cards-Zero Dollar Auth-Card validation (with email)
POST
Valida cartão com transação zero e e‑mail do pagador.
Estornos e Chargebacks
Checkout API-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Total)
POST
Processa reembolso total de um pagamento específico.
Checkout API-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Partial)
POST
Emite reembolso parcial de um pagamento específico.
Checkout API-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Cancel Payment
PUT
Cancela pagamento pre‑autorizado ou pendente.
Checkout API-Refunds, Cancellations & Chargebacks-Chargebacks-Get Chargeback
GET
Consulta informações de chargeback pelo ID.
Checkout API-Refunds, Cancellations & Chargebacks-Chargebacks-Chargeback - Upload documentation
POST
Envio de documentação para disputa de chargeback.
Checkout Pro-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Total)
POST
Realiza reembolso total de um pagamento específico.
Checkout Pro-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Partial)
POST
Reembolsar parcialmente um pagamento específico.
Checkout Pro-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Cancel Payment
PUT
Cancele pagamento (pré-autorizado ou pendente).
Checkout Pro-Refunds, Cancellations & Chargebacks-Chargebacks-Get Chargeback
GET
Exibir detalhes de um chargeback pelo ID.
Checkout Pro-Refunds, Cancellations & Chargebacks-Chargebacks-Chargeback - Upload documentation
POST
Envio de documentação do chargeback.
Checkout Bricks-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Total)
POST
Emite reembolso total de um pagamento.
Checkout Bricks-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Refund Payment (Partial)
POST
Cria reembolso parcial de um pagamento.
Checkout Bricks-Refunds, Cancellations & Chargebacks-Refunds and Cancellations-Cancel Payment
PUT
Cancela pagamento (pré-autorizado e pendente).
Checkout Bricks-Refunds, Cancellations & Chargebacks-Chargebacks-Get Chargeback
GET
Consulta detalhes do chargeback pelo ID.
Checkout Bricks-Refunds, Cancellations & Chargebacks-Chargebacks-Chargeback - Upload documentation
POST
Envio de documentação de contestação de chargeback.
Modelos de Marketplace
Checkout API-Marketplace model-Create Payment (card) - Marketplace Fee
POST
Cria pagamento por cartão incluindo taxa de marketplace.
Checkout Pro-Marketplace model-Create Preference - Marketplace Fee
POST
Cria preferência de checkout com taxa de marketplace.
Checkout Bricks-Marketplace model-Create Payment (card) - Marketplace Fee
POST
Cria pagamento com cartão incluindo taxa de marketplace.
Checkout Bricks-Marketplace model-Create Preference - Marketplace Fee
POST
Cria preferência de checkout adicionando taxa de marketplace à transação.
Utilidades e Configurações (OAuth, Métodos de Pagamento)
Oauth-Connect URL
POST
Redireciona o cliente para a página de autorização.
Oauth-Generate Access Token
POST
Gera token de acesso OAuth para o vendedor.
Oauth-Refresh Access Token
POST
Atualiza o token de acesso para operar em nome do vendedor.
Checkout API-Payment Methods-Get Payment Method
GET
Consulta os métodos de pagamento disponíveis para um determinado BIN.
Checkout API-Payment Methods-Get Installments
GET
Consulta parcelas disponíveis para um BIN e montante de transação.
Checkout API-Identification Types-Get Identification types
GET
Consulta tipos de documentos de identificação por país.
6. Exemplo de Fluxo
Abaixo estão fluxos que usam:
Gateway e Webhook do Studio: rotas para redirecionar pela API do mercado pago
Banco de dados: Um banco de dados simples do Studio com informações de produtos
Módulo do Mercado Pago
A ideia da integração é receber uma requisição apenas com informações da compra específica (ID, por exemplo) e preencher as informações do produto específico recuperando do banco de dados para criar a compra no Mercado Pago. Fora isso, precisamos tratar para onde o usuário será redirecionado em caso de falha ou sucesso, e um gatilho (webhook) que será disparado quando o pagamento for efetuado.
Fluxos principais:
Enviando pagamento
![[Pasted image 20260122105509.png]]
Checando sucesso/falha
![[Pasted image 20260122105951.png]]
7. Links e Referências Úteis
Documentação Oficial da API: https://www.mercadopago.com.br/developers/pt/reference Portal do Desenvolvedor: https://www.mercadopago.com.br/developers/panel Guia de Autenticação: https://www.mercadopago.com.br/developers/pt/docs/your-integrations/credentials
Atualizado
Isto foi útil?