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
Spreedly 3DS2 Global Supported
No
Gateway Specific 3DS2 Supported
No
Populate MIT GSF Support
No
Regions:
Latin America
API endpoint URL:
https://api.mercadopago.com/v1

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>ClNYSBky931hQq1ynqsNwgInqYc</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_adjust type="boolean">false</supports_adjust>
    <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_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_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_network_tokenization type="boolean">false</supports_network_tokenization>
  </characteristics>
  <credentials>
    <credential>
      <name>country</name>
      <value>BR</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <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_field>issuer_id</gateway_specific_field>
    <gateway_specific_field>payment_method_id</gateway_specific_field>
    <gateway_specific_field>processing_mode</gateway_specific_field>
    <gateway_specific_field>merchant_account_id</gateway_specific_field>
    <gateway_specific_field>fraud_scoring</gateway_specific_field>
    <gateway_specific_field>fraud_manual_review</gateway_specific_field>
    <gateway_specific_field>net_amount</gateway_specific_field>
    <gateway_specific_field>taxes</gateway_specific_field>
    <gateway_specific_field>payment_method_option_id</gateway_specific_field>
    <gateway_specific_field>notification_url</gateway_specific_field>
    <gateway_specific_field>capture</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>payer</gateway_specific_field>
    <gateway_specific_field>external_reference</gateway_specific_field>
    <gateway_specific_field>amount</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2021-12-13T11:03:30Z</created_at>
  <updated_at type="dateTime">2021-12-13T11:03:30Z</updated_at>
</gateway>

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.

Processing mode fields

You can specify the gateway processing mode by passing gateway into the processing_mode gateway specific field, which also requires sending in merchant_account_id. You can also optionally send payment_method_option_id to more clearly identify the payment method. In this mode you can further specify the binary fraud_scoring and fraud_manual_review options.

Colombia Specific Tax Fields

Colombian users who wish to add tax information to their purchase transactions can use the net_amount and taxes gateway specific fields. For more information, see the example request below and the MercadoPago IVA Columbia Considerations documentation.

Notification URL

If you have configured a URL with Mercado Pago to receive notifications, you can specify the URL via the notification_url gateway specific field.

Payer

Identifies the buyer

Metadata

Valid JSON that can be attached to the payment to record additional attributes of the merchant

External Reference

ID given by the merchant in their system

Amount

This field enables you to pass a custom amount when using the verify transaction. If no custom amount is passed then it will use the default amount of $1.

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>
            <amount>200</amount>
            <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>
            <processing_mode>gateway</processing_mode>
            <merchant_account_id>56789</merchant_account_id>
            <payment_method_option_id>2134e9010412443882982eba9ad04913</payment_method_option_id>
            <capture>true</capture>
            <fraud_scoring>true</fraud_scoring>
            <fraud_manual_review>false</fraud_manual_review>
            <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",
                    "notification_url": "https://www.mercadopago.com/"
                    "description": "Item description",
                    "category_id": "art", // Available categories at https://api.mercadopago.com/item_categories
                    "quantity": 1,
                    "unit_price": 100
                  }
                ],
                "payer": {
                  "first_name": "Test",
                  "last_name": "Test",
                  "phone": {
                    "area_code": 11,
                    "number": "987654321"
                  },
                  "address": {
                    "zip_code": "85360",
                    "street_name": "Main street"
                    "street_number": 100
                  },
                  "registration_date": "Dec 25th 2020"
                }
              }
            ]]></additional_info>
            <metadata><![CDATA[
              {
                "string_metadata_item": "string",
                "numeric_metadata_item": 100,
                "metadata_list_item": [
                  {
                    "listed_key": "value"
                  }, 
                  {
                    "listed_key": "value"
                  }
                ],
                "nested_metadata_obj": {
                  "key": "value"
                }
              }
            ]]></metadata>
            <payer><![CDATA[
              {
                "entity_type": "individual",
                "type": "customer",
                "id": "134242",
                "email": "jane_doe@example.com",
                "identification": {
                  "type": "customer_id",
                  "number": "54321"
                },
                "phone": {
                  "area_code": "555",
                  "number": "5555555",
                  "extension": "0000"
                },
                "first_name": "jane",
                "last_name": "doe"
              }
            ]]></payer>
            <external_reference>cd4242</external_reference>
            <net_amount>9500</net_amount>
            <taxes>
              <value>500</value>
              <type>IVA</type>
            </taxes>
          </mercado_pago>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2021-12-13T11:03:29Z</created_at>
  <updated_at type="dateTime">2021-12-13T11:03:29Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>JJm1ZtDjI4p0kuptYTLN9dxZUKQ</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"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <mercado_pago>
      <installments>5</installments>
      <amount>200</amount>
      <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>
      <processing_mode>gateway</processing_mode>
      <merchant_account_id>56789</merchant_account_id>
      <payment_method_option_id>2134e9010412443882982eba9ad04913</payment_method_option_id>
      <capture>true</capture>
      <fraud_scoring>true</fraud_scoring>
      <fraud_manual_review>false</fraud_manual_review>
      <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",
                    "notification_url": "https://www.mercadopago.com/"
                    "description": "Item description",
                    "category_id": "art", // Available categories at https://api.mercadopago.com/item_categories
                    "quantity": 1,
                    "unit_price": 100
                  }
                ],
                "payer": {
                  "first_name": "Test",
                  "last_name": "Test",
                  "phone": {
                    "area_code": 11,
                    "number": "987654321"
                  },
                  "address": {
                    "zip_code": "85360",
                    "street_name": "Main street"
                    "street_number": 100
                  },
                  "registration_date": "Dec 25th 2020"
                }
              }
            </additional_info>
      <metadata>
              {
                "string_metadata_item": "string",
                "numeric_metadata_item": 100,
                "metadata_list_item": [
                  {
                    "listed_key": "value"
                  }, 
                  {
                    "listed_key": "value"
                  }
                ],
                "nested_metadata_obj": {
                  "key": "value"
                }
              }
            </metadata>
      <payer>
              {
                "entity_type": "individual",
                "type": "customer",
                "id": "134242",
                "email": "jane_doe@example.com",
                "identification": {
                  "type": "customer_id",
                  "number": "54321"
                },
                "phone": {
                  "area_code": "555",
                  "number": "5555555",
                  "extension": "0000"
                },
                "first_name": "jane",
                "last_name": "doe"
              }
            </payer>
      <external_reference>cd4242</external_reference>
      <net_amount>9500</net_amount>
      <taxes>
        <value>500</value>
        <type>IVA</type>
      </taxes>
    </mercado_pago>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>66</gateway_transaction_id>
  <gateway_latency_ms type="integer">1</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <warning nil="true"/>
  <application_id nil="true"/>
  <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>
  <smart_routed type="boolean">false</smart_routed>
  <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">2021-12-13T11:03:29Z</created_at>
    <updated_at type="dateTime">2021-12-13T11:03:29Z</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">2021-12-13T11:02:33Z</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>
    <callback_url nil="true"/>
    <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 type="boolean">true</eligible_for_card_updater>
    <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>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

Please refer to using a payment method for more information on how to send GSFs

Gateway specific response fields

A purchase, authorize, or capture response from MercadoPago gateway may contain the fields payment_type_id, payment_method_id, issuer_id, and collector_id. These fields tell you the type of payment, card brand, issuer and collector that Mercado Pago inferred for the transaction. A response will also contain an authorization_code when one is generated.

When using the gateway processing_mode, you may receive more gateway specific response fields: processing_mode, merchant_account_id, merchant_number, acquirer, and an acquirer_reconciliation param which will be an array of one or more objects.

Additional gateway specific response fields may include taxes_amount, money_release_date, date_approved, payer_identification_type, and a fee_details object.

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <mercado_pago>
       <processing_mode>aggregator<processing_mode> 
       <payment_type_id>credit_card</payment_type_id>
       <payment_method_id>visa</payment_method_id>
       <issuer_id>1111</issuer_id>
       <authorization_code>123123</authorization_code>
       <collector_id>123456789</collector_id>
       <fee_details>
         <type>mercadopago_fee</type>
         <fee_payer>collector</fee_payer>
         <amount>442</amount>
       </fee_details>
       <taxes_amount>0</taxes_amount>
       <date_approved>2022-10-28T17:15:18.521-04:00</date_approved>
       <money_release_date>2022-10-28T17:15:18.521-04:00</money_release_date>
       <payer_identification_type>RUT</payer_identification_type>
     </mercado_pago>
  </gateway_specific_response_fields>
</transaction>

Syncing Transactions

Spreedly supports updating the status of transactions that have been initiated at the MercadoPago gateway. MercadoPago currently supports using gateway_transaction_id or order_id for updates. The gateway_transaction_id would be the payment_id. While order_id is the external_reference identifier used by the merchant in MercadoPago’s system. See our documentation for more information.