# 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](/skyone-studio/modulos/gestao-de-modulos/criacao-de-modulos.md).

## 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_id` ou `external_store_id`.
  * **POS:** Representa o caixa ou terminal dentro da loja. Identificado por `pos_id` ou `external_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.

## 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:

1. Acesse o [painel de desenvolvedores do Mercado Pago](https://www.mercadopago.com.br/developers/panel).
2. Selecione sua aplicação
3. Navegue até **Credenticias de Produção** (ou Teste).
4. 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

1. No **Skyone Studio**, [crie um módulo](/skyone-studio/modulos/gestao-de-modulos/criacao-de-modulos.md) chamado Mercado Pago. 

2. No módulo do Mercado Pago, na área de Configurações, escolha as seguintes opções:
   * **Conectividade:** REST
   * **Tipo de Autenticação:** Bearer Token
   * **Conta conectada:** clique em **Adicionar conta conectada**

3. Preencha os campos conforme abaixo:

   1. **Nome da conta:** Defina um nome identificável
   2. **Host:** <https://api.mercadopago.com>
   3. **Porta:** 443
   4. **Token:** Insira o `Access Token` (Bearer) obtido no painel.

4. Clique em **Criar conta**.

## 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.               |

{% hint style="info" %}
Leia mais sobre como [adicionar operações dos módulos](/skyone-studio/modulos/configuracoes-and-operacoes/operacoes-de-modulos.md).
{% endhint %}

## 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](https://www.mercadopago.com.br/developers/pt/reference)&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skyone.cloud/skyone-studio/how-to/como-criar-modulo-conector-do-mercado-pago.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.