Como integrar o marketplace via API

Pré-requisitos

Possuir a Checkout API implementado.

Para começar, você deve:

Registrar uma aplicação tipo Marketplace.
Solicitar aos seus fornecedores que se vinculem a ela.
Criar pagamentos em nome de seus vendedores.

1. Como criar sua aplicação

Crie sua aplicação a partir deste link, marcando a opção MP Connect / Marketplace mode e os scopes read, write y offline_access.

Você também deve completar uma Redirect URI a partir da qual os vendedores serão redirecionados para serem vinculados corretamente.

Assim que criar a aplicação, você obterá o APP_ID (identificador de aplicação) necessário para o próximo passo.

2. Vinculação de contas

Para operar no Mercado Pago em nome do seu vendedor, primeiro você deverá lhe solicitar uma autorização.

2.1. Para isso, redirecione o usuário para a seguinte URL substituindo em client_id, o valor de APP_ID e a redirect_uri que configurou no passo anterior:

https://auth.mercadopago.cl/authorization?client_id=APP_ID&response_type=code&platform_id=mp&redirect_uri=http://www.URL_de_retorno.com

2.2. Você receberá o código de autorização na URL que especificou:

http://www.URL_de_retorno.com?code=AUTHORIZATION_CODE

O AUTHORIZATION_CODE será utilizado para criar as credenciais, e será válido durante 10 minutos.

2.3. Você também pode incluir o parâmetro `state` na URL de autorização para identificar a quem corresponde o código que recebeu. Faça isso com segurança, atribuindo neste parâmetro um identificador aleatório exclusivo para cada tentativa.

Incluindo esse parâmetro, a URL de redirecionamento ficaria da seguinte forma:

https://auth.mercadopago.cl/authorization?client_id=APP_ID&response_type=code&platform_id=mp&state=id=RANDOM_ID=&redirect_uri=http://www.URL_de_retorno.com

Agora você receberá o código de autorização e o identificador seguro na URL de retorno especificada:

http://www.URL_de_retorno.com?code=AUTHORIZATION_CODE&id=RANDOM_ID

Não envie informações confidenciais ou credenciais da conta Mercado Pago.

Crie as credenciais de seus vendedores

Utilize o código de autorização obtido no passo anterior para obter as credenciais do usuário mediante a API OAuth para que possa operar em seu nome.

Request:

curl -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/x-www-form-urlencoded' \
     'https://api.mercadopago.com/oauth/token' \
     -d 'client_secret=ACCESS_TOKEN' \
     -d 'grant_type=authorization_code' \
     -d 'code=AUTHORIZATION_CODE' \
     -d 'redirect_uri=REDIRECT_URI'

Os parâmetros que você deve incluir são:

client_secret: seu ACCESS_TOKEN. Pode obter apartir das configurações da sua aplicação.
code: o código de autorização obtido ao redirecionar o usuário de volta para o seu site.
redirect_uri: deve ser a mesma Redirect URI que você configurou na sua aplicação.

Response:

{
    "access_token": "MARKETPLACE_SELLER_TOKEN",
    "public_key": "PUBLIC_KEY",
    "refresh_token": "TG-XXXXXXXXX-XXXXX",
    "live_mode": true,
    "user_id": USER_ID,
    "token_type": "bearer",
    "expires_in": 15552000,
    "scope": "offline_access payments write"
}

Na resposta, além do access_token e da public_keydo vendedor que foi vinculado, você obtém o refresh_token que deve ser utilizado para renovar suas credenciais periodicamente.

Nota

As credenciais têm um prazo de validade de 6 meses. Se não se renovarem as credenciais dos vendedores antes dos 6 meses, as mesmas perderão vigência e se deverá autorizar o vendedor novamente. Recomendação: Renovar as credenciais a cada 5 meses.

Renove as credenciais de seus vendedores

Este processo deve ser efetuado periodicamente para garantir que tenha armazenado em seu sistema as credenciais vigentes dos vendedores, já que são válidas por 6 meses.

Caso encontre qualquer erro no fluxo de pagamento que esteja relacionado ao Access Token que estiver utilizando, atualize automaticamente e tente efetuar o pagamento novamente, antes de exibir um erro ao comprador.

curl -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/x-www-form-urlencoded' \
     'https://api.mercadopago.com/oauth/token' \
     -d 'client_secret= ACCESS_TOKEN' \
     -d 'grant_type=refresh_token' \
     -d 'refresh_token=USER_RT'

Resposta esperada:

{
    "access_token": "MARKETPLACE_SELLER_TOKEN",
    "public_key": "PUBLIC_KEY",
    "refresh_token": "TG-XXXXXXXXX-XXXXX",
    "live_mode": true,
    "user_id": USER_ID,
    "token_type": "bearer",
    "expires_in": 15552000,
    "scope": "offline_access payments write"
}

3. Integre a API para receber pagamentos

Para receber pagamentos em nome de seus vendedores, você deve integrar a API, utilizando oaccess_token e cada fornecedor para a sua aplicação.

Se deseja cobrar uma taxa de comissão por cada pagamento processado pela sua aplicação em nome do seu usuário, simplesmente adicione esse valor no parâmetro application_fee ao criar pagamento:

          
curl -X POST \
        -H 'accept: application/json' \
        -H 'content-type: application/json' \
        -H 'Authorization: Bearer USER_AT' \
        https://api.mercadopago.com/v1/payments \
        -d '{
                "transaction_amount": 100,
                "token": "ff8080814c11e237014c1ff593b57b4d",
                "description": "Title of what you are paying for",
                "installments": 1,
                "payer": {
                        "id": "12345678"
                },
                "payment_method_id": "visa",
                "application_fee": 2.56
        }'

          
<?php  

  require ('mercadopago.php');
  MercadoPago\SDK::configure(['ACCESS_TOKEN' => 'ENV_ACCESS_TOKEN']);

  $payment = new MercadoPago\Payment();

  $payment->transaction_amount = 100;
  $payment->token = "ff8080814c11e237014c1ff593b57b4d";
  $payment->description = "Title of what you are paying for";
  $payment->installments = 1;
  $payment->payment_method_id = "visa";
  $payment->payer = array(
    "email" => "test_user_19653727@testuser.com"
  );

  $payment->save();

?>

          
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");

Payment payment = new Payment();

payment.setTransactionAmount(100f)
      .setToken('ff8080814c11e237014c1ff593b57b4d')
      .setDescription('Title of what you are paying for')
      .setInstallments(1)
      .setPaymentMethodId("visa")
      .setPayer(new Payer("test_user_19653727@testuser.com"));

payment.save();

          
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken(config.access_token);

var payment_data = {
  transaction_amount: 100,
  token: 'ff8080814c11e237014c1ff593b57b4d'
  description: 'Title of what you are paying for',
  installments: 1,
  payment_method_id: 'visa',
  payer: {
    email: 'test_user_3931694@testuser.com'
  }
};

mercadopago.payment.create(payment_data).then(function (data) {
  // Do Stuff...
}).catch(function (error) {
  // Do Stuff...
});

          
require 'mercadopago'
MercadoPago::SDK.configure(ACCESS_TOKEN: ENV_ACCESS_TOKEN)

payment = MercadoPago::Payment.new()
payment.transaction_amount = 100
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.description = 'Title of what you are paying for'
payment.installments = 1
payment.payment_method_id = "visa"
payment.payer = {
  email: "test_user_19653727@testuser.com"
}

payment.save()

O vendedor receberá a diferença entre o valor total e as comissões, tanto a do Mercado Pago como a do Marketplace, assim como qualquer outro valor a ser deduzido da venda.

Dica

Quanto mais informações forem enviadas na geração da preferência, melhor nosso sistema de prevenção a fraude trabalhará com relação à aprovação de pagamentos. Crie uma preferência de pagamento tão completa quanto possa.

Notificações

É necessário que envie sua notification_url, onde receberá um aviso de todos os novos pagamentos e atualizações de status gerados, bem como alta e baixa de usuários no Marketplace.

Você pode receber notificações quando seus clientes autorizarem ou desautorizarem sua aplicação, configurando a URL em sua conta.

Para mais informações, consulte a seção de notificações.

Devoluções e cancelamentos

As devoluções e cancelamentos poderão ser efetuados tanto pelo marketplace como pelo vendedor, através da API ou a partir da conta no Mercado Pago.

Caso a devolução se realize no marketplace, deve-se utilizar as credenciais obtidas para cobrar em nome do vendedor.

Os cancelamentos somente poderão ser efetuados utilizando a API de cancelamentos.

Para mais informações, consulte a seção de devoluções e cancelamentos.

Teste seu Marketplace

É possível testar seu marketplace usando as credenciais de Sandbox da sua conta para associar os vendedores e fazer as cobranças/cancelamentos entre outros.

Você pode usar os cartões de teste fornecidos pelo Mercado Pago e os diferentes prefixos para manipular as mensagens de resposta.

Teste sua integração

Ajude-nos a melhorar a documentação