MercadoPago fact sheet

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 email attribute.
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.

Local Payment Method

Mercado Pago

Mercado Pago (MP) is a leading digital wallet in LATAM. When integrating via Mercado Pago’s own gateway (not through an aggregator), you create a purchase preference, send the payer to MP (if needed), and receive asynchronous notifications. Refunds are supported, but partial refunds may be restricted depending on your account configuration (see internal test notes).

Supported flows: Hosted/Redirect (checkout preference redirect) and Direct server-to-server interactions for post-creation status handling

Payment types: One-shot wallet payments; tokenization/recurring depends on your MP account features (this guide focuses on standard one-shot purchase and refund flows confirmed by internal testing)

Notifications: Asynchronous via MP webhooks/notifications to your public HTTPS endpoint

Key capabilities

Create payment method for Mercado Pago wallet in Spreedly and use it in purchase
Create purchase (preference), redirect the payer (if required), and handle success/rejection via webhooks
Refunds supported; internal notes indicate partial refunds are not permitted on the tested configuration

Constraints and assumptions

Currencies and countries depend on your MP account; confirm enablement with your Mercado Pago representative
Public notification_url is required for asynchronous status updates
Partial refund support may be disabled; internal testing shows full refunds are supported while partials are not

Integration checklist

Obtain and configure Mercado Pago access tokens per country (replace placeholder “country_access_token” with your live/sandbox token)
Set up Spreedly Mercado Pago gateway in your environment
Expose a secure, idempotent notification_url endpoint to process asynchronous updates
Implement a redirect/return UX to bring the payer back to your site after MP approval (if using hosted checkout)

API field reference

Field	Notes
payment_method_type	Use when creating the Spreedly payment method, i.e "mercado_pago"
gateway_specific_fields.mercado_pago.preference.items	Array of items, i.e Title, quantity, unit_price
gateway_specific_fields.mercado_pago.preference.payer	Object, Include payer email and other identifiers as needed
external_reference	Use for idempotency and reconciliation; echoed in webhooks i.e "order-12345"
notification_url	Receives asynchronous updates from MP i.e https://merchant.example.com/mercadopago/notify

Create Mercado Pago payment method

Although Mercado Pago is a wallet, you still create a Spreedly payment method record to reference in purchases. The actual payer interaction and authorization occur on Mercado Pago’s side (preference flow).

POST /v1/payment_methods.json
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "payment_method": {
    "payment_method_type": "mercado_pago",
    "full_name": "Jane Doe",
    "email": "[email protected]"
  }
}

{
  "transaction": {
    "token": "Pm3FP24PecDskKeKQ2JX1aBOdv4",
    "created_at": "2025-12-19T13:43:35Z",
    "updated_at": "2025-12-19T13:43:35Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    "retained": true,
    "state": "succeeded",
    "message": "Succeeded!",
    "payment_method": {
      "token": "MPwPFqbN34Nc5x4lr9iM2aEcD9u",
      "created_at": "2025-12-19T13:43:35Z",
      "updated_at": "2025-12-19T13:43:35Z",
      "email": "[email protected]",
      "storage_state": "retained",
      "payment_method_type": "mercado_pago",
      "full_name": "Jane Doe",
      "errors": []
    }
  }
}
}

Notes:

Use mercado_pago as the payment_method_type
Collect payer identity fields your business requires (e.g., full_name, email)
Persist the returned payment_method token for use in purchase calls.

Create Mercado Pago purchase (preference)

You can create a purchase (preference) via Spreedly which calls Mercado Pago, then you redirect the payer to approve the payment. Final status is received asynchronously.

Request (hosted/redirect preference)

POST /v1/gateways/{gateway_token}/purchase.json
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "transaction": {
    "payment_method_token": "{{mercado_pago_payment_method_token}}",
    "amount": 5000,
    "currency_code": "BRL",
    "order_id": "order-12345",
    "callback_url": "https://merchant.example.com/mercadopago/notify",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "mercado_pago": {
          "purpose": "wallet_purchase",
          "items": [
            { "title": "Order #12345", "quantity": 1, "unit_price": 50.0 }
          ],
          "payer": { "email": "[email protected]" }
      }
    }
  }
}

Notes:

Mercado Pago supports multiple currencies and markets; choose the appropriate currency_code allowed for your account
Populate preference.items and preference.payer per your checkout requirements

Typical response (pending + checkout URL)

{
  "transaction": {
    "token": "2erbIHiLaA5TTTYUxDF8zIunXMP",
    "transaction_type": "OffsitePurchase",
    "state": "pending",
    "amount": 5000,
    "currency_code": "BRL",
    "message": "Pending",
    "response": {
      "success": true,
      "pending": true,
      "checkout_url": "https://www.mercadopago.com/checkout/v1/redirect?pref_id=ABC-123"
    },
    "checkout_url": "https://www.mercadopago.com/checkout/v1/redirect?pref_id=ABC-123",
    "redirect_url": "https://merchant.example.com/return",
    "callback_url": "https://merchant.example.com/mercadopago/notify"
  }
}

Note

Frontend action: redirect the payer to checkout_url to approve the payment. Treat this initial response as non-final; await webhook for outcome.

Webhook notifications

{
  "type": "payment",
  "action": "payment.updated",
  "data": {
    "id": "1234567890",
    "status": "approved",
    "status_detail": "accredited",
    "transaction_amount": 50.0,
    "currency_id": "BRL",
    "external_reference": "order-12345",
    "preference_id": "ABC-123"
  }
}

Recommended handling:

Locate transaction by external_reference or stored mapping to Spreedly transaction token
Map statuses to your order states: approved → paid; rejected / cancelled → failed; in_process → pending
Ensure idempotency for repeated notifications

Status mapping

Status	Description
approved	treat as successful payment; fulfill and expose refund option
in_process / pending	show processing; do not fulfill
rejected / cancelled / expired	mark as failed; allow retry

Refunds

Refunds are issued against the original successful transaction token. Internal testing indicates full refunds succeed and partial refunds are not permitted on the tested configuration. If you send an amount different from the original, Mercado Pago may still apply a full-refund behavior based on transaction rules.

Refund request

POST /v1/transactions/{transaction_token}/credit.json
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "transaction": {
    "amount": 5000,
    "currency_code": "BRL",
    "callback_url": "https://merchant.example.com/mercadopago/refund-notify"
  }
}

Guidelines:

Only refund transactions that are in an approved/settled state
Partial refunds may be disallowed; consult your MP account configuration and observe test behavior

Error handling and retries

Treat initial purchase responses as non-final; rely on webhook notifications for final state
Make webhook processing idempotent (e.g., by referencing external_reference and last known state)
On network failures or ambiguous states, query Mercado Pago’s payment status API (via gateway-specific capabilities) before retrying charges