MercadoPago gateway guide
| Additional notes |
|---|
| MercadoPago has specific 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 the type and value 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 identification
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.
Installments
You can specify the number of installments for the transaction by sending the 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.
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.
Idempotency key
The field idempotency_key enables you pass a unique identifier to the gateway and is required. For more information please refer to the MercadoPago documentation.
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>
<idempotency_key>0d5020ed-1af6-469c-ae06-c3bec19954bb</idempotency_key>
<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": "[email protected]",
"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>
<idempotency_key>0d5020ed-1af6-469c-ae06-c3bec19954bb</idempotency_key>
<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": "[email protected]",
"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>[email protected]</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>
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.
3DS2 Gateway Specific Considerations
In addition to what Spreedly requires for Gateway Specific 3DS you will also need to consider some additional aspects in your requests and during testing.
Gateway Specific Mode
The Gateway Specific Field three_ds_modewill allow you to indicate your preference for 3DS Authentication. The allowed values are "mandatory" or "optional". Choosing "mandatory" will always trigger the gateway's 3DS response, where as "optional" allows the gateway to determine whether or not 3DS authentication is needed.
If no value is sent, Spreedly defaults to "optional".
Transaction Type
3DS only applies for Purchase transactions. Mercado Pago doesn't support 3DS utilizing Authorize-Capture.
Testing 3DS against the sandbox environment
To create a transaction that triggers a 3DS flow on Sandbox you should:
- Create a test account by following the MercadoPago guide.. Use that same test account email in the transaction
emailattribute. - Use the recommend values for credit card listed on the MercadoPago docs.
- Use an amount larger than 3.00 dollars to prevent unexpected results in some regions.
Updated 13 days ago