Feature/cho-api-orders-industry-data

guides/checkout-api-orders/chargebacks-management.en.md

@@ -0,0 +1,99 @@
+# 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:
+
+<pre class="mermaid">
+  sequenceDiagram
+      participant MerchantServer as Merchant Server
+      participant MercadoPagoAPI as Mercado Pago API
+      MerchantServer->>MercadoPagoAPI: Chargeback notification
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: GET Chargeback
+      MercadoPagoAPI-->>MerchantServer: Chargeback response
+      MerchantServer->>MercadoPagoAPI: Upload documentation
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: Chargeback update
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+</pre>
+
+## Consult chargeback
+
+Start the process by consulting the chargeback information using the `id` provided in the notification body. 
+
+From the obtained details, it will be possible to evaluate if there is a need to submit documentation to continue the chargeback.
+
+To consult more information about the chargeback, send a GET request to the endpoint :TagComponent{tag="API" text="/v1/orders/{id}" href="/developers/en/reference/orders/online-payments/get-order/get"}, replacing the `id` field with the `id` of the chargeback brought in the notification body:
+
+```curl
+curl --location --globoff 'https://api.mercadopago.com/v1/chargebacks/{id}' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer {{access_token}}'
+```
+
+Below is an example of a response to the request:
+
+```json
+{
+    "id": "234000062890459000",
+    "payments": [
+        86439942806
+    ],
+    "currency": "ARS",
+    "amount": 1000.50,
+    "reason": "general",
+    "coverage_applied": null,
+    "coverage_elegible": true,
+    "documentation_required": false,
+    "documentation_status": "not_supplied",
+    "documentation": [],
+    "date_documentation_deadline": null,
+    "date_created": null,
+    "date_last_updated": "2024-10-17T12:48:24.000-04:00",
+    "live_mode": true
+}
+```
+
+## Submit documentation for chargeback
+
+In the response to the query made to obtain more information about the chargeback, it will be indicated if you need to submit the necessary documentation to dispute it. You will only need to do so if the `documentation_required` field is true and the `date_documentation_deadline` field indicates a future date.
+
+At this stage, you can submit the documentation proving that the sale is valid through the following POST request:
+
+>WARNING
+>
+> The files must be sent in `.jpg`, `.png`, or `.pdf` format and have a maximum size of up to 10MB.
+
+```
+curl -X POST  \
+-F 'files[]=@/path/to/file/file1.png' \
+-F 'files[]=@/path/to/file/file2.pdf' \
+-H 'Authorization: Bearer {{access_token}}'
+https://api.mercadopago.com/v1/chargebacks/{id}/documentation
+```
+
+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`.
+
+After receiving the documentation, Mercado Pago acts as a mediator in the chargeback resolution process. The analysis is initiated with the card brand, which then sends the received documentation to the card-issuing bank. Once the bank's analysis is completed, the chargeback resolution is determined and the involved parties are notified.
+
+Wait for the Webhook notification regarding the resolution and check the chargeback again using the endpoint :TagComponent{tag="API" text="Get order by ID" href="/developers/en/reference/orders/online-payments/get-order/get"}. After the resolution, the `coverage_applied` field will indicate the result and will assume one of the possible values:
+
+| Value | Description                                                               |
+|-------|---------------------------------------------------------------------------|
+| `true`  | Indicates that the decision was in favor of the seller and the money will be refunded. |
+| `false` | Indicates that the decision was against the seller and the money will be deducted.  |
+
+> RED_MESSAGE
+>
+> The chargeback resolution can take up to 6 months, depending on the card brand.
+
+## Transaction status
+
+When a chargeback is initiated, the status of the associated payment is directly impacted. Initially, the `status` is changed to `charged_back` and the `status_detail` to `in_process`. After the conclusion of the chargeback analysis, whether by the decision of the issuing bank, the determination of eligibility for coverage by Mercado Pago, or the absence of provided documentation, the `status_detail` of the payment will be updated to `settled` or `reimbursed`.
+
+| Status           | Status detail | Description                                                                                      |
+|------------------|---------------|--------------------------------------------------------------------------------------------------|
+| `charged_back`     | `in_process`  | Chargeback received. The payment dispute is in progress, awaiting a final decision.              |
+| `charged_back`     | `settled`     | Decision against the seller. Money withdrawn from the seller's account.                          |
+| `charged_back`     | `reimbursed`  | Decision in favor of the seller. Money refunded to the seller's account.                         |

guides/checkout-api-orders/chargebacks-management.es.md

@@ -0,0 +1,99 @@
+# Gestionar contracargos
+
+Al recibir una notificación de inicio de contracargo, utiliza los datos proporcionados para ayudar en la gestión del proceso. Estos datos serán fundamentales para preparar y enviar la documentación necesaria para la disputa.
+
+En esta etapa, analiza la información detallada incluida en la notificación para comprender los aspectos específicos del contracargo. A continuación, presentamos un diagrama que ilustra cómo funciona el flujo de envío y recepción de la documentación:
+
+<pre class="mermaid">
+  sequenceDiagram
+      participant MerchantServer as Merchant Server
+      participant MercadoPagoAPI as Mercado Pago API
+      MerchantServer->>MercadoPagoAPI: Chargeback notification
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: GET Chargeback
+      MercadoPagoAPI-->>MerchantServer: Chargeback response
+      MerchantServer->>MercadoPagoAPI: Upload documentation
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: Chargeback update
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+</pre>
+
+## Consultar contracargo
+
+Inicia el proceso consultando la información del contracargo utilizando el `id` proporcionado en el cuerpo de la notificación. 
+
+A partir de los detalles obtenidos, será posible evaluar si hay necesidad de enviar la documentación para dar continuidad al contracargo.
+
+Para consultar más información sobre el contracargo, envía un GET al endpoint :TagComponent{tag="API" text="/v1/orders/{id}" href="/developers/es/reference/orders/online-payments/get-order/get"}, sustituyendo el campo `id` por el `id` del contracargo proporcionado en el `body` de la notificación:
+
+```curl
+curl --location --globoff 'https://api.mercadopago.com/v1/chargebacks/{id}' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer {{access_token}}'
+```
+
+A continuación, compartimos un ejemplo de respuesta a la solicitud:
+
+```json
+{
+    "id": "234000062890459000",
+    "payments": [
+        86439942806
+    ],
+    "currency": "ARS",
+    "amount": 1000.50,
+    "reason": "general",
+    "coverage_applied": null,
+    "coverage_elegible": true,
+    "documentation_required": false,
+    "documentation_status": "not_supplied",
+    "documentation": [],
+    "date_documentation_deadline": null,
+    "date_created": null,
+    "date_last_updated": "2024-10-17T12:48:24.000-04:00",
+    "live_mode": true
+}
+```
+
+## Enviar documentación para contracargo
+
+En la respuesta a la consulta realizada para obtener más información sobre el contracargo, se indicará si debe enviar la documentación necesaria para contestarlo. Solo necesitará hacerlo si el campo `documentation_required` es true y el campo `date_documentation_deadline` indica una fecha futura.
+
+En esta etapa, podrá enviar la documentación que demuestre que la venta es válida a través del siguiente POST:
+
+> RED_MESSAGE
+>
+> Los archivos deben enviarse en formato `.jpg`, `.png` o `.pdf` y tener un tamaño máximo de hasta 10MB.
+
+```
+curl -X POST  \
+-F 'files[]=@/path/to/file/file1.png' \
+-F 'files[]=@/path/to/file/file2.pdf' \
+-H 'Authorization: Bearer {{access_token}}'
+https://api.mercadopago.com/v1/chargebacks/{id}/documentation
+```
+
+Si los archivos se envían con éxito, la API devolverá un código `HTTP 200` y el `documentation_status` del contracargo se cambiará a `review_pending`.
+
+Después de recibir la documentación, Mercado Pago actúa como mediador en el proceso de resolución del contracargo. El análisis se inicia junto a la marca de la tarjeta, que luego envía la documentación recibida al banco emisor de la tarjeta. Una vez que el análisis del banco se completa, se determina la resolución del contracargo y se notifica a las partes involucradas.
+
+Espera la notificación Webhook referente a la resolución y verifica nuevamente el contracargo utilizando el endpoint :TagComponent{tag="API" text="Obtener order por ID" href="/developers/es/reference/orders/online-payments/get-order/get"}. Después de la resolución, el campo `coverage_applied` indicará el resultado y asumirá uno de los valores posibles:
+
+| Valor | Descripción                                                                |
+|-------|----------------------------------------------------------------------------|
+| `true`  | Indica que la decisión fue a favor del vendedor y el dinero será devuelto. |
+| `false` | Indica que la decisión fue en contra del vendedor y el dinero será descontado. |
+
+> WARNING
+>
+> La resolución del contracargo puede tardar hasta 6 meses, dependiendo de la marca de la tarjeta.
+
+## Estado de la transacción
+
+Cuando se inicia un contracargo, el estado del pago asociado se ve directamente afectado. Inicialmente, el `status` se cambia a `charged_back` y el `status_detail` a `in_process`. Después de la conclusión del análisis del contracargo, ya sea por la decisión del banco emisor, la determinación de la elegibilidad para cobertura por parte de Mercado Pago o la ausencia de documentación proporcionada, el `status_detail` del pago se actualizará a `settled` o `reimbursed`.
+
+| Status           | Status detail  | Descripción                                                                                      |
+|------------------|----------------|--------------------------------------------------------------------------------------------------|
+| `charged_back`     | `in_process`   | Contracargo recibido. La disputa del pago está en progreso, esperando una decisión final.        |
+| `charged_back`     | `settled`      | Decisión en contra del vendedor. Dinero retirado de la cuenta del vendedor.                      |
+| `charged_back`     | `reimbursed`   | Decisión favorable al vendedor. Dinero reembolsado a la cuenta del vendedor.                     |

guides/checkout-api-orders/chargebacks-management.pt.md

@@ -0,0 +1,99 @@
+# Gerenciar contestações
+
+Ao receber uma notificação de início de contestação, utilize os dados fornecidos para auxiliar no gerenciamento do processo. Esses dados serão fundamentais para preparar e enviar a documentação necessária à disputa.
+
+Nesta etapa, analise as informações detalhadas incluídas na notificação para compreender os aspectos específicos da contestação. Abaixo, apresentamos um diagrama que ilustra como funciona o fluxo de envio e recebimento da documentação:
+
+<pre class="mermaid">
+  sequenceDiagram
+      participant MerchantServer as Merchant Server
+      participant MercadoPagoAPI as Mercado Pago API
+      MerchantServer->>MercadoPagoAPI: Chargeback notification
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: GET Chargeback
+      MercadoPagoAPI-->>MerchantServer: Chargeback response
+      MerchantServer->>MercadoPagoAPI: Upload documentation
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+      MerchantServer->>MercadoPagoAPI: Chargeback update
+      MercadoPagoAPI-->>MerchantServer: HTTP 200
+</pre>
+
+## Consultar contestação
+
+Inicie o processo consultando as informações da contestação utilizando o `id` fornecido no corpo da notificação.
+
+A partir dos detalhes obtidos, será possível avaliar se há necessidade de envio da documentação para dar continuidade ao processo de contestação.
+
+Para consultar mais informações sobre a contestação, envie um GET ao endpoint :TagComponent{tag="API" text="/v1/orders/{id}" href="/developers/pt/reference/orders/online-payments/get-order/get"}, substituindo o campo `id` pelo `id` da contestação trazido no `body` da notificação:
+
+```curl
+curl --location --globoff 'https://api.mercadopago.com/v1/chargebacks/{id}' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer {{access_token}}'
+```
+
+Confira abaixo um exemplo de resposta à requisição:
+
+```json
+{
+    "id": "234000062890459000",
+    "payments": [
+        86439942806
+    ],
+    "currency": "ARS",
+    "amount": 1000.50,
+    "reason": "general",
+    "coverage_applied": null,
+    "coverage_elegible": true,
+    "documentation_required": false,
+    "documentation_status": "not_supplied",
+    "documentation": [],
+    "date_documentation_deadline": null,
+    "date_created": null,
+    "date_last_updated": "2024-10-17T12:48:24.000-04:00",
+    "live_mode": true
+}
+```
+
+## Enviar documentação para contestação
+
+Na resposta à consulta realizada para obter mais informações sobre a contestação, será indicado se você deve enviar a documentação necessária para contestá-lo. Você só precisará fazê-lo se o campo `documentation_required` for true e o campo `date_documentation_deadline` indicar uma data futura.
+
+Nesta etapa, você poderá enviar a documentação que comprove que a venda é válida através do seguinte POST:
+
+> RED_MESSAGE
+>
+> Os arquivos devem ser enviados em formato `.jpg`, `.png` ou `pdf` e ter um tamanho máximo de até 10MB.
+
+```
+curl -X POST  \
+-F 'files[]=@/path/to/file/file1.png' \
+-F 'files[]=@/path/to/file/file2.pdf' \
+-H 'Authorization: Bearer {{access_token}}'
+https://api.mercadopago.com/v1/chargebacks/{id}/documentation
+```
+
+Se os arquivos forem enviados com sucesso, a API retornará um código `HTTP 200` e o `documentation_status` da contestação será alterado para `review_pending`.
+
+Após receber a documentação, o Mercado Pago atua como mediador no processo de resolução da contestação. A análise é iniciada junto à bandeira do cartão, que então envia a documentação recebida ao banco emissor do cartão. Uma vez que a análise do banco é concluída, a resolução da contestação é determinada e as partes envolvidas são notificadas. 
+
+Aguarde a notificação Webhook referente à resolução e cheque novamente a contestação usando o endpoint :TagComponent{tag="API" text="Obter order por ID" href="/developers/pt/reference/orders/online-payments/get-order/get"}. Após a resolução, o campo `coverage_applied` indicará o resultado e assumirá um dos possíveis valores:
+
+| Valor | Descrição                                                                 |
+|-------|---------------------------------------------------------------------------|
+| `true`  | Indica que a decisão foi a favor do vendedor e o dinheiro será devolvido. |
+| `false` | Indica que a decisão foi contra o vendedor e o dinheiro será descontado.  |
+
+> WARNING
+>
+> A resolução da contestação pode levar até 6 meses, dependendo da bandeira do cartão.
+
+## Status da transação
+
+Quando uma contestação é iniciada, o status da transação associada é diretamente impactado. Inicialmente, o `status` é alterado para `charged_back` e o `status_detail` para `in_process`. Após a conclusão da análise da contestação, seja pela decisão do banco emissor, pela determinação da elegibilidade para cobertura pelo Mercado Pago ou pela ausência de documentação fornecida, o `status_detail` do pagamento será atualizado para `settled` ou `reimbursed`.
+
+| Status      | Status detail | Descrição                                                                 |
+|------------------|-------------------|-------------------------------------------------------------------------------|
+| `charged_back`     | `in_process`        | Contestação recebida. A disputa do pagamento está em andamento, aguardando uma decisão final. |
+| `charged_back`     | `settled`           | Decisão contra o vendedor. Dinheiro retirado da conta do vendedor.            |
+| `charged_back`     | `reimbursed`        | Decisão favorável ao vendedor. Dinheiro reembolsado para a conta do vendedor. |