How to create a Mercado Pago connector module

Introduction

This article details how to configure, authenticate, and integrate the Mercado Pago API into Skyone Studio using the module creation option.

What is the Mercado Pago API?

The Mercado Pago API uses a RESTful architecture to allow programmatic interaction with the payment platform. Communication is performed via HTTPS protocol, with standardized data exchange in JSON format. Operations available in the module execute API route calls internally, without the need for direct interaction with endpoints.

Key Capabilities

• Payment Processing: Creation and management of payments via credit card, PIX, boleto, and other local methods, such as PSE (Colombia).

• Physical Store & QR Code Management: Administration of store structures (Stores), cash registers (POS), and generation of dynamic or static QR Codes for in-person payments.

• Point Integration (Card Readers): Management of Point devices, changing operating modes, and creating payment intentions.

• Checkout Pro and Bricks: Creation of payment preferences for web checkout and management of UI components (Bricks).

• Customer and Card Management: Secure storage of customer data and card tokenization for future purchases (One-Click).

Fundamental Concepts

To successfully manipulate data in Mercado Pago, it is essential to understand how information is structured:

• Collector (User/Seller): Represents the Mercado Pago account receiving the funds. Many operations require the userId to identify the owner.

• Store (Physical Store) & POS (Point of Sale): Used primarily in QR Code and Point integrations.

• Preference: The central object of Checkout Pro. It contains sale information (items, values, return URLs) and generates the link for the buyer.

• Payment: The financial record of the transaction. It includes statuses such as approved, pending, or rejected.

• Checkout Types

  • Checkout API (Transparent): Allows creating payments directly via backend using the /v1/payments endpoint. It offers full control over the interface without visible redirection.

  • Checkout Pro (Redirection): Operates by creating Preferences. It automatically manages multiple payment methods in an interface provided by Mercado Pago.

  • Checkout Bricks: A modular layer that can interact with both Checkout Pro preferences and Checkout API payment creation.

All checkout endpoints are in the template, but it's recommended to remove unused ones from your chosen flow to avoid confusion.

Prerequisites and Configuration

To begin development, the following Mercado Pago elements are required:

• Active Mercado Pago Account: Access to the Dashboard.

• Created Application: An application created in the "Your Integrations" area to obtain credentials.

Autentication Type

The API supports OAuth2 and Bearer Token.

Obtaining Credentials

To obtain the credentials, follow these steps:

1. Access the Mercado Pago developer panel.

2. Select your application.

3. Navigate to Production (or Test) Credentials.

4. Copy the Access Token.

Skyone Studio Setup

To connect the modules, you need to create the correct authentication account.

Bearer Token Setup

1. In Skyone Studio, create a module called Mercado Pago.

2. In the Mercado Pago module, in the Settings area, choose the following options:

• Connected Accounts: REST

• Authentication Type: Bearer Token

• Connected Account: Click on Add connected account

3. Fill in the fields as below:

• Account Name: Define an identifiable name

• Host: https://api.mercadopago.com

• Port: 443

• Token: Enter the Access Token (Bearer) obtained from the panel.

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.

Nome da Operação	Método HTTP	Descrição da Função
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.

Nome da Operação	Método HTTP	Descrição da Função
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.

Nome da Operação	Método HTTP	Descrição da Função
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.

Nome da Operação	Método HTTP	Descrição da Função
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.

Nome da Operação	Método HTTP	Descrição da Função
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)

Nome da Operação	Método HTTP	Descrição da Função
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)

Nome da Operação	Método HTTP	Descrição da Função
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

Nome da Operação	Método HTTP	Descrição da Função
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

Nome da Operação	Método HTTP	Descrição da Função
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)

Nome da Operação	Método HTTP	Descrição da Função
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.

Leia mais sobre como adicionar operações dos módulos.

Exemplo de Fluxo utilizando o Mercado Pago

Este exemplo demonstra como construir um fluxo de pagamento utilizando o Skyone Studio, integrando API, banco de dados e o módulo do Mercado Pago, com tratamento de sucesso e falha.

Componentes utilizados no fluxo

Os fluxos apresentados utilizam os seguintes recursos da plataforma:

• API Gateway e Webhook Responsáveis por expor endpoints e receber chamadas externas, permitindo a comunicação entre o sistema cliente e o fluxo no Skyone Studio.

• Banco de dados Um banco de dados simples contendo informações de produtos (por exemplo: ID, nome, preço), utilizado para enriquecer os dados da compra.

• Módulo do Mercado Pago Utilizado para criar e gerenciar pagamentos diretamente na plataforma do Mercado Pago.

---

Objetivo da integração

A integração foi desenhada para receber uma requisição com dados mínimos da compra, como o ID do produto, e a partir disso:

1. Consultar o banco de dados do Skyone Studio para recuperar as informações completas do produto.

2. Montar os dados necessários para a criação do pagamento no Mercado Pago.

3. Enviar a solicitação de pagamento para o Mercado Pago.

4. Tratar os cenários de sucesso ou falha, definindo corretamente o retorno ao sistema chamador.

5. Processar notificações assíncronas por meio de um webhook, disparado quando o status do pagamento for atualizado.

---

Fluxos principais

A solução é composta por dois fluxos principais:

1. Enviando pagamento

Este fluxo é responsável por iniciar o processo de pagamento:

• Recebe a requisição via API Gateway, contendo o identificador da compra ou do produto.

• Executa uma consulta no banco de dados do Studio para obter os dados completos do produto.

• Realiza validações básicas (por exemplo, se o produto existe).

• Monta a estrutura de dados esperada pelo Mercado Pago.

• Envia a solicitação de criação do pagamento utilizando o módulo do Mercado Pago.

• Retorna ao cliente o resultado inicial da criação do pagamento (como link ou status).

2. Checando sucesso ou falha

Este fluxo é responsável por validar o resultado do pagamento:

• Recebe uma chamada (via API ou webhook).

• Consulta o banco de dados ou o status retornado pelo Mercado Pago.

• Avalia o resultado utilizando uma condição (IF), separando os cenários de:

  • Pagamento aprovado (sucesso)

  • Pagamento recusado ou com erro (falha)

• Retorna a resposta adequada para cada cenário, garantindo que o sistema cliente saiba como prosseguir.

Leia também: Documentação Oficial da API do Mercado Pago