Configurar a vinculação

A criação da vinculação gera o link de autorização que deve ser apresentado ao comprador para que ele conceda ao vendedor o acesso à sua carteira do Mercado Pago. Há dois fluxos disponíveis: Padrão, no qual o comprador conclui a autorização no navegador, e Sniffing, que tenta abrir a autorização diretamente no aplicativo do Mercado Pago em dispositivos móveis. Compare as opções abaixo e escolha a que melhor se adequa à sua integração.

curl
curl -X POST \
    'https://api.mercadopago.com/v2/wallet_connect/agreements' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
  "return_uri": "https://www.mercadopago.com/",
  "external_flow_id": "{{EXTERNAL_FLOW_ID}}",
  "external_user": {
    "id": "usertest",
    "description": "Test account"
  },
  "agreement_data": {
    "validation_amount": 3.14,
    "description": "Test agreement"
  }
}'

json
{
  "agreement_id": "22abcd1235ed497f945f755fcaba3c6c",
  "agreement_uri": "{{wc_agreement_uri_example}}"
}

Após criar a vinculação, redirecione o comprador para a agreement_uri retornada na resposta. Nesse endereço, o comprador concede a autorização para que o vendedor utilize a sua carteira do Mercado Pago como meio de pagamento.

Ao finalizar o fluxo, o Mercado Pago redireciona o comprador para a return_uri informada na criação, acrescentando o resultado da operação como query parameters.

• Em caso de autorização concedida, a return_uri será chamada no formato abaixo.

plain
`{return_uri}?agreement_id={agreement_id}&code={code}&flow=agreement&external_flow_id={external_flow_id}&code_type=validation_code`

• Já em caso de recusa ou cancelamento por parte do comprador, a return_uri será chamada no formato abaixo, sem o parâmetro code e com o parâmetro error.

plain
`{return_uri}?agreement_id={agreement_id}&flow=agreement&external_flow_id={external_flow_id}&error={error}`

O token de pagamento (payer_token) é a credencial que representa a autorização do comprador e permite ao vendedor executar cobranças a partir da sua carteira, sendo a última etapa do fluxo de vinculação. O parâmetro code necessário para gerá-lo pode ser obtido de duas formas: como query parameter na return_uri (recomendado) ou a partir da notificação Webhook de confirmação da vinculação.

Para gerar o token, envie uma solicitação ao endpoint /v2/wallet_connect/agreements/{agreement_id}/payer_tokenPOST, incluindo seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. No Wallet Connect, o Access Token e a Public Key são repassados pela equipe responsável por criar a sua aplicação, tanto os de teste quanto os de produção. Também é possível visualizá-los em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`., o agreement_id da vinculação obtido na sua criação e o código de autorização.

curl
curl -X POST \
    'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}/payer_token' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
  "code": "{{AUTHORIZATION_CODE}}"
}'

Consulte na tabela abaixo as descrições dos parâmetros que devem ser enviados nesta requisição.

Se a solicitação for bem-sucedida, a resposta retornará o status 201 com o token de pagamento associado à vinculação.

json
{
  "payer_token": "abcdef1e23f4567d8e9123eb6591ff68df74c57930551ed980239f4538a7e530"
}

O cancelamento revoga a autorização concedida pelo comprador e invalida o payer_token associado, impedindo novas cobranças a partir da sua carteira.

Para cancelar uma vinculação, envie uma solicitação ao endpoint /v2/wallet_connect/agreements/{agreement_id}DELETE sem enviar o body na requisição. Certifique-se de incluir seu Access Token de testeChave privada utilizada no backend para autenticar as requisições. No Wallet Connect, o Access Token e a Public Key são repassados pela equipe responsável por criar a sua aplicação, tanto os de teste quanto os de produção. Também é possível visualizá-los em Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e o agreement_id da vinculação que deseja cancelar.

curl
curl -X DELETE \
    'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta retornará o status 200 sem corpo de resposta, indicando que a vinculação foi cancelada e que o payer_token associado deixou de ser válido.