In Mercado Pago, we continue to work on improving the experience for our integrators. Recently, we've seen an increase in duplicated payments and refunds, which is why we've decided to make it mandatory to use the idempotency header (X-Idempotency-Key) in requests to the Payments and Refunds API.

An idempotency key is a unique identifier. By including this key in the API request header, you are informing the server that the request is idempotent, meaning that the result of the operation will be the same regardless of how many times the request is processed.

By using this key, the server can recognize duplicated requests and ensure that only the first one is processed. This is crucial in cases of network failures, timeouts, or automatic resending, where the same request can be sent multiple times.

The idempotency key allows the server to distinguish between a new request and a repetition, avoiding the repeated execution of the associated operation. This practice is especially relevant in sensitive operations such as financial transactions, where unwanted repetitions can cause issues.

If you are using our SDKs, you just need to update to versions that already include idempotency usage. If you are directly calling our APIs, you will need to generate and include the idempotency key in the header of your API calls.

The incorporation of this functionality will be mandatory for all new integrations or implementations starting from 09/01/2024, for use in Sandbox.

If your integration predates this date and you will not have new implementations, including idempotency will not be mandatory for now. However, we recommend that you update your integration to improve your billing experience and stay up to date with Mercado Pago's solutions and products.

Access the documentation for Payments and Refunds API to learn more.