AI resources

Manage chargebacks

Upon receiving a chargeback initiation notification, use the provided data to assist in managing the process. This data will be essential for preparing and submitting the necessary documentation for the dispute.

In this stage, analyze the detailed information included in the notification to understand the specific aspects of the chargeback. Below, we present a diagram that illustrates how the document submission and receipt flow works:

sequenceDiagram
    participant Server as Merchant server
    participant API as Mercado Pago API

    API->>Server: Chargeback notification
    Server-->>API: HTTP 200
    Server->>API: Get chargeback
    API->>Server: Chargeback response
    Server->>API: Upload supporting documentation
    API-->>Server: HTTP 200
    API->>Server: Chargeback update
    Server-->>API: HTTP 200

Consult chargeback

Start the process by consulting the chargeback information using your case_id or payment_id returned in the body of the notification configured for the chargebacks topic. Based on the details obtained, prepare the supporting documentation to be submitted to proceed with the chargeback process.

The documentation_required field is legacy. Regardless of whether the returned value is true or false, always submit supporting documentation to substantiate the chargeback dispute and demonstrate the validity of the sale.

To consult more information about the chargeback, send a request to the /v1/chargebacks/{id}GET endpoint with your production Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it in Your integrations > Integration data > Production > Production credentials., using the chargeback case_id received in the notification body.

curl
curl -X GET \
  'https://api.mercadopago.com/v1/chargebacks/{id}' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'X-Caller-Id: <YOUR_SELLER_ID>'

Parameter	Type	Description and examples	Requirement
`id`	Path. String	Numeric identifier (`case_id`) of the chargeback case returned in the body of the configured notification for chargebacks. For example, `234000062890459000`.	Required
`Authorization`	Header. String	Refers to your private key, the production Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Production > Production credentials..	Required
`X-Caller-Id`	Header. Integer	ID of the authenticated user (`seller ID`) and owner of the requested resource. For example: `123456789`.	Required

Below is an example of a response to the request:

json
{
    "id": "234000062890459000",
    "payments": [
        86439942806
    ],
    "currency": "ARS",
    "amount": 1000.50,
    "reason": "unauthorized",
    "reason_id": "6",
    "coverage_applied": null,
    "coverage_eligible": true,
    "documentation_status": "not_supplied",
    "documentation": [],
    "date_documentation_deadline": null,
    "date_created": "2024-02-01T10:30:00.000-03:00",
    "date_last_updated": "2024-10-17T12:48:24.000-04:00",
    "live_mode": true
}

Below are the possible values of the documentation_status field:

Value	Description
`pending`	The supporting documentation has not yet been submitted by the seller.
`review_pending`	The supporting documentation was submitted and is pending review by the Mercado Pago team.
`valid`	The submitted supporting documentation was reviewed and considered valid.
`invalid`	The submitted supporting documentation was reviewed and considered invalid.
`not_supplied`	No supporting documentation was submitted within the established deadline.
`not_applicable`	The API classified supporting documentation as not applicable to this case. This status is independent of the legacy `documentation_required` field; submit files when `documentation_status` is `pending`.

For more information about all the parameters available and involved in this chargeback process, visit our API ReferenceAPI.

Submit supporting documentation

You must always submit supporting documentation to substantiate the chargeback dispute and demonstrate the validity of the sale. These documents allow the Mercado Pago team to analyze the facts and mediate the resolution with the card brand and issuing bank.

Supporting documentation can only be submitted once per case. To confirm whether the case already has documentation submitted, check the /v1/chargebacks/{id}GET endpoint to confirm that documentation_status=pending and that the case can receive files.
Remember that the documentation_required field is legacy, so regardless of the returned value, always submit supporting documentation to substantiate the chargeback dispute.

To submit the evidence files that prove the validity of the sale, send a request to the /v1/chargebacks/{id}/documentationPOST endpoint with your production Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it in Your integrations > Integration data > Production > Production credentials., using the chargeback case_id.

curl
curl -X POST \
  'https://api.mercadopago.com/v1/chargebacks/{id}/documentation' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'X-Caller-Id: <YOUR_SELLER_ID>' \
  -H 'X-Idempotency-Key: <SOME_UNIQUE_VALUE>' \
  -F 'file=@/path/to/file/file1.png' \
  -F 'file=@/path/to/file/file2.pdf'

Parameter	Type	Description and examples	Requirement
`id`	Path. String	Numeric identifier of the chargeback case (`case_id`) returned in the body of the configured notification for chargebacks. For example, `234000062890459000`.	Required
`Authorization`	Header. String	Refers to your private key, the production Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Production > Production credentials..	Required
`X-Caller-Id`	Header. Integer	ID of the authenticated user (`seller ID`) and owner of the requested resource. For example: `123456789`.	Required
`file`	Body. Array	Evidence file(s) (invoices, shipping proofs, screenshots, etc.) in JPEG, PNG, or PDF format. Maximum 10 files with a total size of up to 10 MB.	Required

If the files are successfully submitted, the API will return an HTTP 200 code and the documentation_status of the chargeback will be changed to review_pending. The response will include the list of uploaded files:

json
[
    {
        "type": "collector",
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "url": "https://storage.mlstatic.com/op/123/456789/file1.png",
        "description": "file1.png"
    },
    {
        "type": "collector",
        "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "url": "https://storage.mlstatic.com/op/123/456789/file2.pdf",
        "description": "file2.pdf"
    }
]

For more information about all the parameters available and involved in this chargeback process, visit our API ReferenceAPI.

View submitted documentation files

After submitting the supporting documentation, you can download the files or access each one individually through the URL available in the url field of the documentation array.

To view or download a specific file, send a request to the /v1/chargebacks/documentation/{type}/{uuid}GET endpoint with your production Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it in Your integrations > Integration data > Production > Production credentials., replacing {type} with the document category and {uuid} with the file's unique identifier.

curl
curl -X GET \
  'https://api.mercadopago.com/v1/chargebacks/documentation/{type}/{uuid}' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'X-Caller-Id: <YOUR_SELLER_ID>'

Parameter	Type	Description and examples	Requirement
`type`	Path. String	Document category. The only allowed value is `collector`, corresponding to files uploaded by the seller.	Required
`uuid`	Path. String	Unique file identifier, obtained from the `documentation` array in the response of the /v1/chargebacks/{id}GET endpoint. For example, `a1b2c3d4-e5f6-7890-abcd-ef1234567890`.	Required
`Authorization`	Header. String	Refers to your private key, the production Access TokenPrivate key of the application created in Mercado Pago and used in the backend. You can access it through Your integrations > Integration data > Production > Production credentials..	Required
`X-Caller-Id`	Header. Integer	ID of the authenticated user (`seller ID`) and owner of the requested resource. For example: `123456789`.	Required

The file is returned with its original MIME type (image/jpeg, image/png, or application/pdf), allowing it to be rendered directly in the browser or saved locally.

For more information about all the parameters available and involved in this chargeback process, visit our API ReferenceAPI.

Chargeback resolution

After the supporting documentation is submitted and the analysis by the card brand and the issuing bank is completed, the chargeback resolution is determined and the involved parties are notified.

Wait for the Webhook notification regarding the resolution and consult the chargeback again using the /v1/chargebacks/{id}GET endpoint. After the resolution, the coverage_applied field will indicate the result:

Value	Description
`true`	The decision was in favor of the seller and the money will be refunded.
`false`	The decision was against the seller and the money will be deducted.

The chargeback resolution can take up to 6 months, depending on the card brand.

PreviousConfigure chargeback notificationsLearn how to configure chargeback notifications.