MercadoPago Gateway Guide
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
andverify
. In Chile, Colombia, Mexico, Peru and Uruguay onlypurchase
andrefund
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
andcardholder_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.