MercadoPago Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
MercadoPago
Services that work with Spreedly:
  • MercadoPago
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify
Supported payment types:
Credit Card
Regions:
Latin America

Authentication and Security

Specific names for credentials:
Country, Access Token

Onboarding Merchants in:

Additional Notes

MercadoPago has a couple requirements to successfully run transactions.

  • You must send an email address with all of your transactions. You can send an email address by creating a payment method with one or sending one directly in the transaction request body itself.
  • In Brazil and Argentina there is support for purchase, authorize, capture, void, refund and verify. In Chile, Colombia, Mexico, Peru and Uruguay only purchase and refund are supported.
  • Your MercadoPago credentials are tied to a specific country and currency. You must send the country associated with a particular access_token when creating a new MercadoPago gateway. Spreedly expects the two character country code.

    AR - Argentina
    BR - Brazil
    CL - Chile
    CO - Colombia
    MX - Mexico
    PE - Peru
    UY - Uruguay

  • With the exception to Mexico, MercadoPago requires sending the payer identification with each payment. You can send those two values via the cardholder_identification_type and cardholder_identification_number gateway specific fields.

Adding a MercadoPago gateway

To add a MercadoPago gateway:


curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>mercado_pago</gateway_type>
        <country>BR</country>
        <access_token>Your access_token</access_token>
      </gateway>'

<gateway>
  <token>OkgPRZ2drCSg0pxLwSFJwwbYLfw</token>
  <gateway_type>mercado_pago</gateway_type>
  <name>MercadoPago</name>
  <description nil="true"/>
  <country>BR</country>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_disburse type="boolean">false</supports_disburse>
  </characteristics>
  <credentials>
    <credential>
      <name>country</name>
      <value>BR</value>
    </credential>
  </credentials>
  <gateway_specific_fields>
    <gateway_specific_field>cardholder_identification_type</gateway_specific_field>
    <gateway_specific_field>cardholder_identification_number</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>statement_descriptor</gateway_specific_field>
    <gateway_specific_field>device_id</gateway_specific_field>
    <gateway_specific_field>additional_info</gateway_specific_field>
    <gateway_specific_field>binary_mode</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2018-06-19T17:07:47Z</created_at>
  <updated_at type="dateTime">2018-06-19T17:07:47Z</updated_at>
</gateway>

Optional Gateway Specific Fields

Payer Identificaiton

In order to process through Mercado Pago, you must send the payer identification on each payment. This information is mandatory for all Mercado Pago’s sites except for Mexico. For more details see the MercadoPago developer docs.

https://www.mercadopago.com.ar/developers/en/api-docs/custom-checkout/identification-types

Installments

You can specify the number of installments for the transaction by sending installments field. If this field is not sent, Spreedly will default your installments to 1.

Statement Descriptor

An arbitrary string to be displayed on your customer’s credit card statement. You can specify it with the statement_descriptor field.

Additional information

You can specify certain classes of additional information as a JSON blob supplied via the additional_info field. Providing this information when available will improve transaction approval rates. For more information, see the MercadoPago developer documentation.

Device Session ID

You can specify a device session ID via the device_id gateway specific field. Specifying this when available will improve transaction approval rates.

Binary Mode

To allow transactions to have a state of in_process, set the binary_mode gateways specific field to false, otherwise it will remain true. Transactions in an in_process state can be reviewed using Mercado Pago webhooks

Issuer ID and Payment Method ID

You can override the inferred card brand on a transaction-by-transaction basis by providing the issuer_id and payment_method_id gateway specific fields. Please see the official gateway documentation for more information.

Example


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <mercado_pago>
            <installments>5</installments>
            <cardholder_identification_type>DNI</cardholder_identification_type>
            <cardholder_identification_number>22222222</cardholder_identification_number>
            <statement_descriptor>Your descriptor</statement_descriptor>
            <device_id>277feb7c-28fc-4874-b89b-f3422732c860</device_id>
            <binary_mode>false</binary_mode>
            <issuer_id>1234</issuer_id>
            <payment_method_id>visa_debit</payment_method_id>
            <additional_info><![CDATA[
              {
                "items": [
                  {
                    "id": "item-ID-1234",
                    "title": "Title of what you are paying for",
                    "picture_url": "https://www.mercadopago.com/org-img/MP3/home/logomp3.gif",
                    "description": "Item description",
                    "category_id": "art", // Available categories at https://api.mercadopago.com/item_categories
                    "quantity": 1,
                    "unit_price": 100
                  }
                ]
              }
            ]]></additional_info>
          </mercado_pago>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2018-11-08T21:20:58Z</created_at>
  <updated_at type="dateTime">2018-11-08T21:20:58Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>5AQ0wGeu2zGYRqdk3u6FnwimzrM</token>
  <transaction_type>Purchase</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <gateway_specific_fields>
    <mercado_pago>
      <installments>5</installments>
      <cardholder_identification_type>DNI</cardholder_identification_type>
      <cardholder_identification_number>22222222</cardholder_identification_number>
      <statement_descriptor>Your descriptor</statement_descriptor>
      <device_id>277feb7c-28fc-4874-b89b-f3422732c860</device_id>
      <binary_mode>false</binary_mode>
      <issuer_id>1234</issuer_id>
      <payment_method_id>visa_debit</payment_method_id>
      <additional_info>
              {
                "items": [
                  {
                    "id": "item-ID-1234",
                    "title": "Title of what you are paying for",
                    "picture_url": "https://www.mercadopago.com/org-img/MP3/home/logomp3.gif",
                    "description": "Item description",
                    "category_id": "art", // Available categories at https://api.mercadopago.com/item_categories
                    "quantity": 1,
                    "unit_price": 100
                  }
                ]
              }
            </additional_info>
    </mercado_pago>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>56</gateway_transaction_id>
  <gateway_latency_ms type="integer">23</gateway_latency_ms>
  <amount type="integer">100</amount>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2018-11-08T21:20:58Z</created_at>
    <updated_at type="dateTime">2018-11-08T21:20:58Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2018-11-08T20:13:35Z</updated_at>
    <email>joey@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater nil="true"/>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
</transaction>

Gateway Specific Response Fields

A purchase, authorize, or capture response from MercadoPago gateway may contain the fields payment_type_id, payment_method_id, and issuer_id. These fields tell you the type of payment, card brand, and issuer that Mercado Pago inferred for the transaction.