Usage

How it works

Basically the SDK is a super enhance REST Client with powerful tools. Almost each resource (Payment, Preference, etc...) have basic methods:

• create (POST)
• update (PUT)
• get (GET)
• remove (DELETE)

Those methods are dynamically created by the SDK. Each one has the following parameters.

mercadopago.resource.create( ..., configurations, callback );

mercadopago.resource.create( ..., configurations ).then().catch();

Configurations Parameter

This parameter is optional if you are not using callbacks. This will automatically convert into an empty object.

The configurations parameter is a JSON Object that allow the next values:

• qs:

This is a JSON Object with the parameters you want to send over the querystring. Let's do an example trying to get all my payments.

If we see the Search API, this is going to be a GET, and we need to send payer.id = me on the querystring. To do this, we only need to do:

var configurations = {
  qs: {
    'payer.id': 'me'
  }
};

mercadopago.payment.search(configurations, callback);

Sending that on the qs will convert the output url to:

https://api.mercadopago.com/v1/payments/search?payer.id=me

• idempotency - Custom idempotency uuid to be send

In some cases a connection issue could interrupt an operation. To ensure that the operation is complete you can retry it. But, in some cases the operation was complete. When you retry the operation, you may cause a duplication.

To avoid that behaviour you can use an UUID (Universally Unique Identifier) that identifies the operation. This UUID is going to be a header on the request call Idempotency-Key. This headers is going to be automatically generated by the first operation.

If an operation fails the error is going to have the Idempotency-Key sended. You can use this key to retry the operation. Let's see and example:

var payment = {
  description: 'Buying a PS4',
  transaction_amount: 10500,
  payment_method_id: 'rapipago',
  payer: {
    email: 'test_user_3931694@testuser.com',
    identification: {
      type: 'DNI',
      number: '34123123'
    }
  }
};

mercadopago.payment.create(payment).then(function (mpResponse) {
  console.log(mpResponse);
}).catch(function (mpError) {
  return mercadopago.payment.create(payment, {
    qs: {
      idempotency: mpError.idempotency
    }
  });
}).then(function(mpResponse){
  console.log(mpResponse);
});

The first response is going to be:

mercadopagoError {
  name: 'MercadoPagoError',
  message: 'Lost Connection',
  cause: 'Unknown Cause',
  status: 500,
  idempotency: '7fea2db6-fc84-436f-b6f4-457f7f5f151e'
}

On the second try you are sending the same idempotency that identifies the previous payment creation. Doing this you ensure to be avoiding duplication.

Also, you can save the idempotency and the original JSON payload to retry it later.

• access_token

If you want, you can override the access_token configured. If you are using MP Connect and you wan't to impersonate a Merchant using his credentials you can override it on the operation you wan't to execute. For example:

var payment = {
  description: 'Buying a PS4',
  transaction_amount: 10500,
  payment_method_id: 'rapipago',
  payer: {
    email: 'test_user_3931694@testuser.com',
    identification: {
      type: 'DNI',
      number: '34123123'
    }
  }
};

mercadopago.payment.create(payment, {
  access_token: 'MY_MERCHANT_ACCESS_TOKEN',
}).then(function (mpResponse) {
});

In this example a Payment is going to be created using my merchant access_token ('MY_MERCHANT_ACCESS_TOKEN')

Callback Parameter

The callback is optional. If you are going to use promises you can avoid sending it:

mercadopago.resource.create( ..., configurations, callback );

mercadopago.payment.get(1, {}, function(error, response){
  if (error) return console.log('An error ocurred: ' + error.message);

  console.log(response);
});

mercadopago.resource.create( ... ).then().catch();

mercadopago.payment.get(1).then(function (response) {
  console.log(response);
}).then(function (error) {
  console.log('An error ocurred: ' + error.message);
});

Dynamic Parameters

We already said that the last two parameters are configurations and callback, but what about the first parameters?. Depending on the method (POST, GET, etc...) and the path the parameters are going to change.

First we are going to start talking about the path. Let's see the different type of paths:

• /v1/payments - No path variables
• /v1/payments/:id - One path variable
• /v1/customers/:id/cards/:card_id - Two path variables

This means that the method you call needs to get this variable (id, card_id) on some way. This is when the method comes in the way. Let's see some methods

payment.create = requestManager.describe({
  path: '/v1/payments',
  method: 'POST'
});

payment.update = requestManager.describe({
  path: '/v1/payments/:id',
  method: 'PUT'
});

payment.get = requestManager.describe({
  path: '/v1/payments/:id',
  method: 'GET'
});

There is a difference between methods that receive a JSON payload and the ones that don't.

• No Payload: GET, DELETE
• With Payload: POST, PUT, PATCH

Without Payload

GET, DELETE: This are going to receive the variables on the parameters. Let's see an example:

payment.get = requestManager.describe({
  path: '/v1/payments/:id',
  method: 'GET'
});

// Calling the get
mercadopago.payment.get(1, {}, function (){});

customers.cards.get = requestManager.describe({
  path: '/v1/customers/:id/cards/:card_id',
  method: 'GET'
});

// Getting the card 10 from the customer 1
mercadopago.customers.cards.get(1, 10, {}, function ()  {});

With Payload

POST, PUT, PATH: This are going to match the variables with the ones on the payload. Let's see an example:

payment.update = requestManager.describe({
  path: '/v1/payments/:id',
  method: 'PUT'
});

// Calling the update
mercadopago.payment.update({
  id: 1,
  status: 'cancelled'
}, function (){});

customers.cards.update = requestManager.describe({
  path: '/v1/customers/:id/cards/:card_id',
  method: 'PUT'
});

// Calling the update
mercadopago.customers.cards.update({
  id: 1,
  card_id: 10,
  expiration_year: 2020
}, function (){});

The path variable name must be the same in the payload. All the names already are the same ones that you need to send on the update.

A good example will be:

mercadolibre.payment.get(1).then(function (mpResponse) { // Cancelling a payment return mercadolibre.payment.update({ id: mpResponse.body.id, status: 'cancelled' }); }).catch(function (error) { console.log('An error ocurred updating the payment'); });