> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velan.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MercadoPago

> Como conectar sua conta Mercado Pago à Velan via OAuth 2.0 com PKCE.

A integração MercadoPago usa o fluxo **OAuth 2.0 com PKCE** (Proof Key for Code Exchange). O processo é iniciado pelo painel da Velan e, após a autorização, os tokens são armazenados automaticamente.

<Note>
  Só é permitida **uma** integração MercadoPago ativa por empresa.
</Note>

***

## Passo a passo

<Steps>
  <Step title="Acesse Integrações e clique em INTEGRAR">
    No painel da Velan, acesse **Integrações** no menu lateral e localize o card do **Mercado Pago**. Clique em **INTEGRAR**.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2001.png" alt="Step 01 — Tela de Integrações com card Mercado Pago" />
    </Frame>
  </Step>

  <Step title="Clique em CONECTAR">
    Você será direcionado para a página de detalhes da integração. Clique em **CONECTAR** para iniciar o fluxo OAuth.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2002.png" alt="Step 02 — Botão CONECTAR na página de detalhes" />
    </Frame>
  </Step>

  <Step title="Selecione o país Brasil">
    Você será redirecionado para o Mercado Pago. Na tela de seleção de país, escolha **Brasil**.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2003.png" alt="Step 03 — Seleção de país no Mercado Pago" />
    </Frame>
  </Step>

  <Step title="Confirme o país selecionado">
    Com **Brasil** selecionado, clique em **Confirmar** para prosseguir.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2004.png" alt="Step 04 — Confirmar país Brasil" />
    </Frame>
  </Step>

  <Step title="Autorize a integração">
    Revise as permissões que serão concedidas à Velan e clique em **Autorizar**.

    As permissões solicitadas são:

    * **Leitura** — acesso a dados do perfil e movimentações
    * **Acesso Offline** — manutenção do acesso até você cancelar a autorização
    * **Write** — criação de cobranças e links de pagamento

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2005.png" alt="Step 05 — Tela de autorização de permissões no Mercado Pago" />
    </Frame>
  </Step>

  <Step title="Retorno para a Velan">
    Após a autorização, o Mercado Pago redireciona automaticamente para a Velan.

    <Tabs>
      <Tab title="Sucesso">
        Sua conta foi vinculada com sucesso. Clique em **Hora de começar a faturar!** para voltar ao painel.

        <Frame>
          <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2006.png" alt="Step 06 — Mercado Pago conectado com sucesso" />
        </Frame>
      </Tab>

      <Tab title="Falha">
        Se ocorrer algum erro durante a autorização, você verá a tela de falha. Clique em **Tentar novamente** para reiniciar o fluxo ou **Voltar para integrações** para retornar ao painel.

        <Frame>
          <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2006%20-%20fail.png" alt="Step 06 Fail — Falha ao conectar Mercado Pago" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Integração ativa">
    Com a conexão realizada, o card do Mercado Pago exibirá o status **Ativo** e o botão **GERENCIAR** estará disponível.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/velanapp/images/mercadopago/Step%2007.png" alt="Step 07 — Card Mercado Pago ativo com botão GERENCIAR" />
    </Frame>
  </Step>
</Steps>

***

## Fluxo OAuth (referência técnica)

A Velan inicia o fluxo com **PKCE (S256)** para o endpoint de autorização do Mercado Pago:

```
https://auth.mercadopago.com/authorization?
  client_id=...&
  response_type=code&
  platform_id=mp&
  state={company_code}&
  redirect_uri=...&
  code_challenge={challenge}&
  code_challenge_method=S256&
  country_id=MLB
```

Após a autorização, o Mercado Pago redireciona para o callback da Velan, que troca o `code` pelos tokens e ativa a integração automaticamente.

| Resultado | Redirecionamento                               |
| --------- | ---------------------------------------------- |
| Sucesso   | `/dashboard/integrations/mercado-pago-success` |
| Falha     | `/dashboard/integrations/mercado-pago-fail`    |

***

## Integração de co-produtor (parceiro)

<Warning>
  Esta modalidade **não está disponível para autoatendimento**. Para habilitar a integração de co-produtor, entre em contato com o suporte da Velan.
</Warning>

Parceiros com acesso à empresa podem conectar sua própria conta MercadoPago para habilitar **split de pagamento**. O fluxo é iniciado pelo painel na seção de membros da empresa — o parceiro autoriza sua conta MP e a Velan passa a usá-la como receiver nas transações de split.