Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Order

Order negotiation platform

Introduction

In this section, we will present a detailed description of the Entities, Events, Payloads, and the REST API used in the development of this integration. It is important that you have a thorough understanding of the fundamental components that make up this integration, enabling a successful implementation.The Order Negotiation Platform is a tool designed to facilitate, manage, and streamline negotiations between two parties, with the purpose of resolving issues related to ORDERS. It acts as an intermediary and enables effective communication between the parties involved, allowing the exchange of proposals and facilitating the search for effective agreements.

Scenarios

Order Cancellation

During the process of canceling an order, instead of simply canceling the order, the platform initiates a negotiation between the Customer and the Partner.In this negotiation, the Customer expresses their intention to cancel the order, and the Trading Platform sends an event to the Partner.The Partner then has the opportunity to assess the situation and whether the cancellation is justified. To this end, the Trading Platform provides specific endpoints where the Partner can accept the cancellation, reject the cancellation, or offer a counteroffer, making a decision based on the negotiation.Actors:

Partner
Customer

Item Reshipment - Experimental for some customers - Coming soon

After receiving the order, if the customer notices that one or more items were not shipped, they initiate a resend request process through the Order Trading Platform, which initiates an interaction between the Customer and the Partner. In this interaction, the Customer communicates their intention to receive the missing items, and the Trading Platform sends an event to the Partner. The Partner, in turn, has the opportunity to assess the situation and decide whether resending the items is the best solution. To this end, the Trading Platform offers specific access endpoints, where the Partner can accept the resending of items, reject the resending of items, or offer a counteroffer. This decision is made based on the negotiation process.Actors:

Partner
Customer

Quick Guide to Integration

This section describes the essential steps that must be followed for successful integration. All components mentioned in this guide are detailed throughout the documentation.Make sure to implement the appropriate logic to handle these events and their respective actions, ensuring that the integration occurs correctly and efficiently.

Step 1 - Mapping the EntitiesMap the entities HandshakeDispute, HandshakeSettlement, DisputeAlternative, SelectedDisputeAlternative, Media, Item, GarnishItem, and Amount.Step 2 - Consuming the EventsUsing the polling mechanism, implement the consumption of the HANDSHAKE_DISPUTE and HANDSHAKE_SETTLEMENT events. This functionality will allow you to receive notifications about disputes and decisions made during the negotiation. The previously mapped entities are used in these events.Step 3 - Integrating with RESTAPIDevelop the integration for the /accept, /reject, and /alternative endpoints, which are responsible for responding to Disputes represented by the HANDSHAKE_DISPUTE event. These endpoints will be essential for managing and making decisions related to Disputes.Step 4 - Processing the HANDSHAKE_DISPUTE EventFor each HANDSHAKE_DISPUTE event received, it must be responded to by a provided endpoint. This action can be ACCEPT, REJECT, or MAKE COUNTERPROPOSAL.The /alternative endpoint should only be used for flows that include a counteroffer. This situation is fully documented throughout this document.If the HANDSHAKE_DISPUTE event is not responded to within the specified time, the Trading Platform will respond automatically. The timeout mechanism is fully documented throughout this documentation.Once the HANDSHAKE_DISPUTE has been responded to by an available endpoint, it is not possible to respond again.It is strongly recommended to avoid automating trade acceptance or rejection decisions. Automating this process can lead to a negative customer experience and financial losses.It is crucial to analyze each trade individually, taking into account the specific circumstances, and make an appropriate decision based on established policies and guidelines.Step 5 - Processing the HANDSHAKE_SETTLEMENT EventFor each HANDSHAKE_SETTLEMENT event received, no further action is expected. However, this event signals that the HANDSHAKE_DISPUTE event was properly responded to and processed by the platform.

Entities and Attributes

Below, we present details about the entities and constants used in event payloads and the REST API.Entities

HandshakeDispute
HandshakeSettlement
DisputeAlternative
SelectedDisputeAlternative
Media
Item
GarnishItem
Amount

Constants

handshakeType
handshakeGroup
action
timeoutAction
status
type
negotiationReasons

We begin with a description of the main entities:

HandshakeDispute
HandshakeSettlement

Next, we detail the entities that make up the main entities:

DisputeAlternative
SelectedDisputeAlternative
Media
Item
GarnishItem
Amount

Finally, we detail the constants that will be used during the flow:HandshakeDispute

handshakeType
handshakeGroup
timeoutAction
action

HandshakeSettlement

status

DisputeAlternative

type

Each attribute is accompanied by a brief explanation of its purpose, the supported data type, and whether the attribute is required or optional.For constants, the possible available values and a brief explanation of their purpose are listed.It is important to emphasize that the inclusion of non-required fields is justified by the fact that they are used only in specific flows, which will be fully explored throughout this document.

Entities

HandshakeDispute

The HandshakeDispute entity is used in the HANDSHAKE_DISPUTE event, which contains essential information about the ongoing negotiation, such as the handshake type (handshakeType), handshake grouping (handshakeGroup), the purpose of the Dispute (action), the evidence (evidences) and comments (message) sent by the consumer, the maximum time to respond to the event (expiresAt), and the action to be taken if the response time expires (timeoutAction).When the ongoing negotiation includes the Refund Proposal functionality, additional attributes, such as DisputeAlternative, are also provided.In negotiations related to Partial Cancellation Requests, the Items (Item) and/or GarnishItems (GarnishItem) attributes are sent, detailing the products included in the request.Required FieldsNon-required fields are used only in specific workflows. Examples of when and how these attributes are received can be seen throughout the documentation.

Attribute	Description	Type	Values	Required
id	Dispute Id	uuid	-	yes
parentDisputeId	Dispute Id that originated a counterproposal. For example, in the Refund Proposal flow	uuid	-	no
action	Action that the Dispute represents, what is the purpose of the negotiation?	String	CANCELLATION, PARTIAL_CANCELLATION, PROPOSED_AMOUNT_REFUND, PROPOSED_ADDITIONAL_TIME, or VOID	yes
message	Message associated with the reason for the Dispute (negotiation). For cancellation flows, represents the cancellation justification provided by the consumer	String	-	yes
alternatives	Alternative responses that are available, in addition to accepting/rejecting the Dispute. Contains the information that can be sent in the refund proposal flow, for example.	List of DisputeAlternative	-	no
expiresAt	Maximum time for the negotiation to be responded to before the automatic action is automatically triggered.	DateTime	-	yes
createdAt	Date and time the Dispute was created	DateTime	-	yes
handshakeType	Type of negotiation initiated	String	AFTER_DELIVERY, DELAY, PREPARATION_TIME, or AFTER_DELIVERY_PARTIALLY	yes
handshakeGroup	Handshake grouping.	String	CUSTOMER_ORDER_SUPPORT	yes
timeoutAction	Automatic action to be executed if the Handshake is not responded to within the time period determined by expiresAt.	String	ACCEPT_CANCELLATION, REJECT_CANCELLATION, or VOID	yes
metadata.item	Contains the list of items that can be canceled in the Partial Cancellation flow. In Disputes with the PARTIAL_CANCELLATION action.	List of Item	-	no
metadata.garnishItems	Contains the list of sub-items that can be canceled in the Partial Cancellation flow. In Disputes with the PARTIAL_CANCELLATION action.	List of GarnishItem	-	no
metadata.evidences	Media sent by the consumer when opening the cancellation. Actions CANCELLATION and PARTIAL_CANCELLATION.	List of Media	-	no
metadata.acceptCancellationReasons	List of strings with possible reasons why the merchant accepted the cancellation requested by the customer.	List of String	NegotiationReasons	no

HandshakeSettlement

The HandshakeSettlement entity is used in the HANDSHAKE_SETTLEMENT event and contains relevant information about the dispute that was responded to, including the dispute ID (id), the dispute resolution status (status), and the reason for the dispute rejection, if applicable (reason).When the flow includes the Refund Proposal functionality, additional attributes are also provided, such as SelectedDisputeAlternative.Required FieldsNon-required fields are used only in specific flows. Examples can be found throughout the documentation to see when and how these attributes are received.

Attribute	Description	Type	Values	Required
id	Generated Settlement ID	uuid	-	yes
disputeId	Dispute ID	uuid	-	yes
status	Represents the final result of the negotiation related to a Dispute (disputeId)	String	ACCEPTED, REJECTED, EXPIRED, or ALTERNATIVE_REPLIED	yes
reason	Represents the justification for rejecting or accepting a given negotiation. In cases of Disputes related to the cancellation request, the field is required when the status is REJECTED.	String	-	no
selectedDisputeAlternative	Represents the data sent during the response of a Dispute with ALTERNATIVE_REPLIED status. For example, during the execution of the Refund Proposal flow.	SelectedDisputeAlternative	-	no

DisputeAlternative

The DisputeAlternative entity is used in conjunction with the HandshakeDispute entity, being sent when the Dispute, for example, is related to a transaction that has the Refund Proposal functionality.

Attribute	Description	Type	Values	Required
id	The ID of the DisputeAlternative that should be used to respond to a specific Dispute. For example, during the execution of the Refund Proposal flow.	uuid		yes
type	Action that can be performed after the transaction is finalized.	String	REFUND, BENEFIT, or ADDITIONAL_TIME	Yes
metadata.maxAmount	Maximum monetary amount possible to be sent in the response to a given Dispute. For example, during the Refund Proposal flow, when the partner has the option to send a monetary amount of up to 80% of the order value to avoid cancellation.	Amount		Required only when the type is REFUND or BENEFIT
metadata.allowedsAdditionalTimeInMinutes	List with numeric values that the partner can choose to determine how much extra time they need to deliver the order. For example, during the delay negotiation flow, when the partner has the option to ask the customer to wait an additional X minutes for the order to be delivered.	List of Int		Required only when the type is ADDITIONAL_TIME
metadata.allowedsAdditionalTimeReasons	List of reasons for the order delivery delay that the store must provide when negotiating a new delivery time.	List of String	NegotiationReasons	Required only when the type is ADDITIONAL_TIME

SelectedDisputeAlternative

The SelectedDisputeAlternative entity is used in conjunction with the HandshakeSettlement entity sent when the Dispute was responded to with ALTERNATIVE_REPLIED. It represents the type and contains the relevant metadata of the counteroffer sent.

Attribute	Description	Type	Values	Required
id	ID of the selected DisputeAlternative of the Dispute with counteroffer options.	uuid		yes
type	Type of DisputeAlternative selected during the Dispute response.	String	REFUND or BENEFIT	yes
metadata.amount	Monetary amount sent in the counteroffer. For example, during the Refund Proposal flow, when the partner sends a monetary amount of up to 80% of the order value to avoid cancellation.	Amount		Required only when the type is REFUND or BENEFIT
metadata.allowedsAdditionalTimeInMinutes	List with numeric values so the partner can choose how much extra time they need to deliver the order. For example, during the Delay Negotiation flow, when the partner has the option to ask the customer to wait an additional X minutes for the order to be delivered.	List of Int		Required only when the type is ADDITIONAL_TIME
metadata.allowedsAdditionalTimeReasons	List of reasons for the order delivery delay that the store must provide when negotiating a new delivery time.	List of String	NegotiationReasons	Required only when the type is ADDITIONAL_TIME

Media

The Media entity is used in conjunction with the HandshakeDispute entity and contains the media sent by the consumer.

Attribute	Description	Type	Required
url	URL of the media sent by the consumer	String	yes
contentType	Type of media sent	String	yes

WarningTo make a request using the URL returned in the Media object variable, you must be authenticated.

Item

The Item entity is used in conjunction with the HandshakeDispute entity and contains information about the items being canceled, for example, during the execution of the Partial Cancellation Request flow.

Attribute	Description	Type	Required
id	Catalog ID	UUID	yes
uniqueId	Unique ID of the item in the order	UUID	yes
externalCode	Item ID in the integrator	String	yes
quantity	Quantity of items	int	yes
index	Index in the bag	int	yes
amount	Unit value of the item	Amount	yes
reason	Consumer's justification for canceling the item in question. For example: Product arrived different from what was ordered.	String	no

GarnishItem

The GarnishItem entity is used in conjunction with the HandshakeDispute entity and contains information about GarnishItems being canceled, for example, during the Partial Cancellation Request flow.

Attribute	Description	Type	Required
id	Catalog ID	UUID	yes
parentUniqueId	Unique ID of the parent item	UUID	yes
externalCode	ID of the garnish item in the integrator	String	yes
quantity	Quantity of garnishItems being canceled	int	yes
index	Index in the bag	int	yes
amount	Unit value of the garnish item	Amount	yes
reason	Consumer's justification for canceling the item in question. For example: The combo soda didn't arrive.	String	no

Amount

The Amount entity is used in conjunction with the DisputeAlternative and SelectedDisputeAlternative entities, and contains the amount and currency.

Attribute	Description	Type	Required
value	Monetary value entered without decimal places based on the currency. For example: R$0.99 = 99 R$1.00 = 100 R$13.99 = 1399	String	yes
currency	Currency unit used. For orders placed in Brazilian Reais, the amount sent is BRL	String	yes

Reference: ISO 4217 — Currency codes

Constants

Below, we present the possible values for the attributes of the HandshakeDispute entity: handshakeType, handshakeGroup, action, and timeoutAction. We also detail the status attributes present in the HandshakeSettlement entity and the type attributes present in the DisputeAlternative and DisputeSelectedAlternative entities.

handshakeType

Identifies the type of handshake. Present in the HandshakeDispute entity.

Value	Description
AFTER_DELIVERY	Represents a Negotiation for a cancellation request after delivery
DELAY	Represents a Negotiation for a cancellation request for an order that is late in delivery
PREPARATION_TIME	Represents a Negotiation for a cancellation request for an order that is being prepared by the partner
AFTER_DELIVERY_PARTIALLY	Represents a Negotiation for a partial cancellation request after delivery

handshakeGroup

Classifies the handshake into a group. Present in the HandshakeDispute entity.

Value	Description
CUSTOMER_ORDER_SUPPORT	Indicates that the negotiation is due to a customer request.

action

Identifies the type of action being negotiated in the Dispute. Present in the HandshakeDispute entity.

Value	Description
CANCELLATION	Indicates that the negotiation is a Full Cancellation Request
PARTIAL_CANCELLATION	Indicates that the negotiation is a Partial Cancellation Request
PROPOSED_AMOUNT_REFUND	Indicates that the negotiation is a Cancellation Request with the possibility of making a Refund Proposal.

timeoutAction

Identifies the automatic action that will be executed if the handshake response time expires. The expiration time is defined in the expiresAt attribute, and both are in the HandshakeDispute entity.

Value	Action
ACCEPT_CANCELLATION	Will cancel the order
REJECT_CANCELLATION	Will not cancel the order
VOID	Does not have any automatic action

status

Identifies the status of the negotiation. Present in the HandshakeSettlement entity.

Value	Description
ACCEPTED	Indicates that the Dispute was accepted
REJECTED	Indicates that the Dispute was rejected
EXPIRED	Indicates that the Dispute exceeded the maximum response time and was automatically responded to
ALTERNATIVE_REPLIED	Indicates that the Dispute was successfully responded to in a flow that contains a counteroffer. For example, in the Refund Proposal flow.

type

Identifies the type of item that can be offered in a counteroffer. Present in the DisputeAlternative and SelectedDisputeAlternative entities.

Value	Description
REFUND	Indicates that a monetary amount will be sent as a refund proposal.
BENEFIT	This is a benefit (voucher or discount) that will be offered to the customer, to be used on future purchases.

NegotiationReasons

List of standardized reasons that the store can choose to inform why it accepted, rejected, or sent a counterproposal to the cancellation requested by the customer.

Value	Description
HIGH_STORE_DEMAND	High demand in the store.
STORE_SYSTEM_ISSUES	System problems in the store.
LACK_OF_DRIVERS	Lack of delivery drivers.
OPERATIONAL_ISSUES	Operational problems.
ORDER_OUT_FOR_DELIVERY	Order out for delivery.
DRIVER_IS_ALREADY_AT_THE_ADDRESS	The delivery person is already at the address.
OTHER_REASONS	Other reasons.

Events - Payload

In this section, we provide detailed information about the HANDSHAKE_DISPUTE and HANDSHAKE_SETTLEMENT events, which are part of the negotiation process.The payloads presented in this section contain all possible attributes, ensuring a complete overview of their structure, including those that are not mandatory and only apply to specific flows.Throughout the documentation, each flow will be detailed with the exact payload that will be propagated. This approach will provide a clear understanding of how each event works during the negotiation process.For more information about attributes, see the Entities and Attributes section.

HANDSHAKE_DISPUTE

The HANDSHAKE_DISPUTE event indicates that a proposal has been made and must be responded to.To respond to the HANDSHAKE_DISPUTE event, it is essential to use the accept, reject, or alternative endpoints to indicate the decision on the proposal under negotiation. These options allow you to specify whether the proposal will be accepted, rejected, or a counterproposal will be presented.If a HANDSHAKE_DISPUTE event is not responded to by human interaction within a pre-determined timeframe, it will be automatically responded to by the Negotiation Platform. For more details on the automatic response in case of a timeout, see the Timeout section.The aforementioned endpoints will be detailed throughout the documentation.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "message":"Pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "alternatives":[
      {
        "id":"2d35d0b9-67ae-46d2-8261-f0a40e5d07fd", 
        "type":"REFUND", 
        "metadata":{
          "maxAmount":{
            "value":"6000", 
            "currency":"BRL"
          }
        }
      },
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ], 
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ],
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

HANDSHAKE_SETTLEMENT

The HANDSHAKE_SETTLEMENT event signals and formalizes that a proposal has been previously responded to through the accept, reject, or alternative endpoints.This event contains information about the status of the Dispute.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "receivedAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":{
      "id":"2d35d0b9-67ae-46d2-8261-f0a40e5d07fd", 
      "type":"REFUND", 
      "metadata":{
        "amount":{
          "value":"1500", 
          "currency":"BRL"
        }
      }
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }
}

REST API

In this section, we provide detailed information about the implementation of the Trading Platform's REST API. This API follows the principles of REST architecture, which allows communication between systems through HTTP requests, following a resource-based approach and using HTTP verbs (GET, POST) to perform operations.Developers can access the endpoints through specific URLs, send requests, and receive responses in JSON format.It is important to follow the API documentation to construct the correct requests and interpret the responses.

Accept Proposal

This endpoint allows you to ACCEPT a received Dispute. This Dispute is represented by the HANDSHAKE_DISPUTE event.When sending a request to this endpoint, the system will process the response and perform the corresponding actions related to the handshake process. It is necessary to provide the correct Dispute ID to associate the response with the desired transaction.

URL

POST order/v1.0/disputes/{disputeId}/acceptBodyThis payload only needs to be sent in the request body when the metadata.acceptCancellationReasons event receives the metadata.

{
"reason":"HIGH_STORE_DEMAND",
"detailReason":"Only if you want to detail the reason for accepting the cancellation"
}

Parameter Description

Attribute	Description	Type
disputeId	The "disputeId" parameter represents the unique identifier of the Dispute being responded to. It is a unique value assigned to each Negotiation in the system.	uuid

Description of Message Body Attributes

Attribute	Description	Type	Size	Required
reason	This field is used to provide the reason why the order cancellation was accepted. It must be filled with a constant from the `metadata.acceptCancellationReasons` metadata of the HANDSHAKE_DISPUTE event.	String	-	Only when the `metadata.acceptCancellationReasons` metadata is present in the HANDSHAKE_DISPUTE event
detailReason	It must be filled with a clear and specific explanation of why the cancellation was accepted by the merchant.	String	250 Characters	no

Status Code

When a request is made to the Trading Platform API, the response received will include status codes that indicate what is happening on the server side. In this section, you can view the status codes you will find in the responses, along with their meaning.

Response Success

1 - The request was processed successfully

HTTP Status	Description
201 Created	Returned when processing was successful.

Body

{
  "id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37", 
  "status":"ACCEPTED", 
  "disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8", 
  "createdAt":"2023-06-23T13:29:49.218951237Z"
}

Response Failure

1 - Unauthorized

HTTP Status	Description	Cause
401 Unauthorized	Returned when the client is not authenticated/authorized	The client is not properly authenticated/authorized

2 - Dispute not found

HTTP Status	Description	Cause
404 Not Found	Returned when the Dispute was not found.	The Dispute ID provided does not match any existing Dispute in the system

Body

{
"code":"DISPUTE_NOT_FOUND",
"message":"Dispute with ID {} was not found"
}

3 - Dispute has already been processed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the Dispute has already been responded to.	A response has already been sent to the Dispute and another response cannot be sent.

Body

{
"code":"DISPUTE_ALREADY_ANSWERED",
"message":"Dispute with ID {} has already been answered"
}

4 - Handshake already completed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the handshake is already completed.	The handshake for the specified Dispute ID has already been completed and the process cannot be repeated

Body

{
"code":"HANDSHAKE_ALREADY_CONCLUDED",
"message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

5 - Non-existent or invalid cancellation reason

HTTP Status	Description	Cause
400 Bad Request	Returned when there is a need to send the reason why the store is accepting the cancellation.	The `reason` value must be sent in the body of the request with the value contained in the `metadata.acceptCancellationReasons` metadata of the HANDSHAKE_DISPUTE event. It is worth remembering that this field is only mandatory if, and only if, the metadata `metadata.acceptCancellationReasons` is in the event HANDSHAKE_DISPUTE.

Body

{
  "code":"INVALID_CANCELLATION_REASON", 
  "message":"_Dispute_ ID {} requires a valid reason to cancel the order"
}

Reject Proposal

This endpoint allows you to REJECT a received Dispute. This Dispute is represented by the HANDSHAKE_DISPUTE event.When sending a request to this endpoint with the rejection reason, the system will process the response and perform the corresponding actions related to the handshake process.

URL

POST order/v1.0/disputes/{disputeId}/reject Body

{
"reason":"Reason for rejecting the Proposal"
}

It is essential to note that the reason field must be included when making this request. If this field is omitted, the request will result in an appropriate exception, containing an explanatory error message along with the corresponding code.Parameter Description

Attribute	Description	Type
disputeId	The "disputeId" parameter represents the unique identifier of the Dispute being responded to. It is a unique value assigned to each Negotiation in the system	uuid

Description of message body attributes

Attribute	Description	Type	Size	Required
reason	This field is used to provide the reason why the order cancellation cannot be accepted. It must be filled in with a clear and specific explanation of why the cancellation cannot be performed.	String	250 Characters	Yes

Status Codes

Response Success

1 - The request was processed successfully

HTTP Status	Description
201 Created	Returned when processing was successful.

Body

{
"id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37",
"status":"REJECTED",
"reason":"Justification for rejecting the proposal",
"disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8",
"createdAt":"2023-06-23T13:29:49.218951237Z"
}

Attribute Description

Attribute	Description	Type
id	Unique identifier of the dispute/accept endpoint return. Represented by a string of alphanumeric characters.	UUID
status	The status of the Dispute after the request made to the dispute/accept endpoint will be updated to "REJECTED", indicating that the Dispute was successfully accepted. This "REJECTED" value serves as confirmation that the Dispute was processed and accepted by the system.	String
reason	Description of the reason for the cancellation rejection	String
disputeId	Unique identifier of the Dispute associated with the dispute/accept endpoint return. It is a sequence of alphanumeric characters that identifies a specific Dispute, for example, "63ddd317-90fd-43ad-830c-532f9848b7f8".	UUID
createdAt	The "createdAt" field indicates the exact date and time the action was processed.	DateTime

Response Failure

1 - Unauthorized

HTTP Status	Description	Cause
401 Unauthorized	Returned when the client is not authenticated/authorized	The client is not properly authenticated/authorized

2 - Required fields were not submitted

HTTP Status	Description	Cause
400 Bad Request	Returned when required fields are not submitted in the Dispute request.	Required fields have not been filled in.

Body

{
  "code":"DISPUTE_REQUIRED_FIELDS_WERE_NOT_SENT", 
  "message":"The request is missing the required field, \"reason\" that needs to be included"
}

3 - Reason field contains more characters than allowed

HTTP Status	Description	Cause
400 Bad Request	Returned when the partner's justification in the Dispute is too long and exceeds the defined limit.	The justification provided by the partner exceeds the defined character limit

Body

{
"code":"DISPUTE_FIELD_EXCEEDS_MAXIMUM_LENGTH",
"message":"The \"reason\" field exceeds the maximum allowed length. Please ensure that the field does not exceed 250 characters"
}

4 - Dispute not found

HTTP Status	Description	Cause
404 Not Found	Returned when the Dispute was not found	The provided Dispute ID does not match any existing Dispute in the system

Body

{
"code":"DISPUTE_NOT_FOUND",
"message":"Dispute with ID {} was not found"
}

5 - Dispute has already been processed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the Dispute has already been responded to previously.	A response has already been sent to the Dispute and another response cannot be sent

Body

{
"code":"DISPUTE_ALREADY_ANSWERED",
"message":"Dispute with ID {} has already been answered"
}

6 - Handshake already completed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the handshake is already completed.	The handshake for the specified Dispute ID has already been completed and cannot be repeated.

Body

{
"code":"HANDSHAKE_ALREADY_CONCLUDED",
"message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

Make Counteroffer

This endpoint allows you to MAKE A COUNTEROFFER for a received Dispute. This Dispute is represented by the HANDSHAKE_DISPUTE event.When you send a request to this endpoint, the system will process the response and perform the corresponding actions related to the process.

URL

POST order/v1.0/disputes/{disputeId}/alternatives/{alternativeId}Body - REFUND

{
  "type":"REFUND", 
  "metadata":{
    "amount":{
      "value":"1500", 
      "currency":"BRL"
    }
  }
}

Body - BENEFIT

{
  "type":"BENEFIT", 
  "metadata":{
    "amount":{
      "value":"1500", 
      "currency":"BRL"
    }
  }
}

Body - ADDITIONAL_TIME

{
  "type":"ADDITIONAL_TIME", 
  "metadata":{
    "additionalTimeInMinutes": 15,
    "additionalTimeReason": "ORDER_OUT_FOR_DELIVERY"
  }
}

Parameter Description

Attribute	Description	Type
disputeId	The "disputeId" parameter represents the unique identifier of the Negotiation being responded to. It is a unique value assigned to each Negotiation in the system.	uuid
alternativeId	The "id" field represents the unique identifier of the alternative being responded to. It is a unique value assigned to each DisputeAlternative in the system. When using this field, you must provide the correct ID to ensure your response is associated with the correct Dispute. Be sure to include the appropriate value for this field when submitting your response to the API.	uuid

Attribute Description

Attribute	Description	Type	Values
type	Describes the type of Alternative being responded to.	String	REFUND, BENEFIT, or ADDITIONAL_TIME
metadata.amount	Attribute responsible for the amount and currency information that will be sent in the counteroffer.	Amount
metadata.additionalTimeInMinutes	Attribute responsible for informing the delay time until delivery that the restaurant wishes to negotiate with the customer.	String	See more
metadata.additionalTimeReason	Attribute responsible for informing the reason the partner is negotiating a new delivery time for the order.	String	See more

Status Codes

When a request is made to the Trading Platform API, the response will include status codes that indicate what is happening on the server side. In this section, you can view the status codes you will find in the Trading Platform API responses, along with their meaning.

Response Success

1 - The request was processed successfully

HTTP Status	Description
201 Created	Returned when processing was successful.

Body

{ 
"id":"adee6f8d-7112-4d12-b2e8-5ddf01c11a37", 
"status":"ALTERNATIVE_REPLIED", 
"disputeId":"63ddd317-90fd-43ad-830c-532f9848b7f8", 
"createdAt":"2023-06-23T13:29:49.218951237Z"
}

Response Failure

1 - Não autorizado

HTTP Status	Description	Cause
401 Unauthorized	Returned when the client is not authenticated/authorized	The client is not properly authenticated/authorized

2 - Dispute not found

HTTP Status	Description	Cause
404 Not Found	Returned when the Dispute was not found.	The Dispute ID provided does not match any existing Dispute in the system

Body

{
"code":"DISPUTE_NOT_FOUND",
"message":"Dispute with ID {} was not found"
}

3 - Dispute has already been processed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the Dispute has already been responded to.	A response has already been sent to the Dispute and another response cannot be sent.

Body

{
"code":"DISPUTE_ALREADY_ANSWERED",
"message":"Dispute with ID {} has already been answered"
}

4 - Alternative not found

HTTP Status	Description	Cause
404 Not Found	Returned when the Dispute was not found.	The provided Alternative ID does not match any existing Alternative in the system

Body

{
"code":"DISPUTE_NOT_FOUND",
"message":"Dispute with ID {} was not found"
}

5 - Alternative ID is incorrect

HTTP Status	Description	Cause
400 Bad Request	Returned when the Dispute alternative was not found.	The provided Alternative ID does not match any existing Alternative in the system.

Body

{
"code":"DISPUTE_ALTERNATIVE_INVALID",
"message":"Alternative with ID {} from _Dispute_ with ID {} was invalid"
}

6 - Alternative type is invalid

HTTP Status	Description	Cause
400 Bad Request	Returned when the alternative type is invalid	The provided alternative type is not invalid.

Body

{
"code":"DISPUTE_ALTERNATIVE_TYPE_INVALID",
"message":"Alternative Type {} with ID {} from _Dispute_ with ID {} was invalid. Must be one of the following available types {}"
}

7 - Handshake already completed

HTTP Status	Description	Cause
422 Unprocessable Entity	Returned when the handshake is already completed.	The handshake for the provided Dispute ID has already finished and the process cannot be repeated

Body

{
"code":"HANDSHAKE_ALREADY_CONCLUDED",
"message":"Handshake with ID {} and _Dispute_ ID {} has already been concluded"
}

8 - Negotiation delay reason is invalid

HTTP Status	Description	Cause
400 Bad Request	Returned when the `additionalTimeReason` metadata does not contain one of the expected values.	The `metadata.additionalTimeReason` value must be sent in the request body with the value contained in the `alternatives.metadata.allowedsAdditionalTimeReasons` metadata of the HANDSHAKE_DISPUTE event.

Body

{
"code":"HANDSHAKE_NEGOTIATION_TIME_INVALID_REASON",
"message":"Alternative ID {} was replied with invalid negotiation time reason"
}

9 - Additional delay negotiation time is invalid

HTTP Status	Description	Cause
400 Bad Request	Returned when the `additionalTimeInMinutes` metadata does not contain one of the expected values.	The `metadata.additionalTimeInMinutes` value must be sent in the request body with the value contained in the `alternatives.metadata.allowedsAdditionalTimeMinutes` metadata of the HANDSHAKE_DISPUTE event.

Body

{
"code":"HANDSHAKE_NEGOTIATION_TIME_INVALID_TIME_IN_MINUTES",
"message":"Alternative ID {} was replied with invalid additional time in minutes"
}

Timeout

When a HANDSHAKE_DISPUTE event is published and not responded to within the established timeframe, an automatic action is triggered, resulting in the generation of a HANDSHAKE_SETTLEMENT event with the EXPIRED status, informing the decision that was made and the negotiation closed.The maximum time to respond to a Dispute is defined by the expiresAt attribute.The automatic action to be executed is described by the timeoutAction attribute and can have the following values:

Value	Action
VOID	Does not perform any automatic action. Only the HANDSHAKE_SETTLEMENT with the "EXPIRED" status is generated, formalizing the decision made.
ACCEPT_CANCELLATION	This action cancels the order, generating the HANDSHAKE_SETTLEMENT events with the "EXPIRED" status and the "CANCELLED" event to indicate that the order was successfully canceled.
REJECT_CANCELLATION	This operation rejects the order cancellation. The HANDSHAKE_SETTLEMENT events with the "EXPIRED" status and the "CANCELLATION_REQUEST_FAILED" event will be generated to indicate that the order could not be canceled.

Use Cases - Examples

Available Negotiations

The following will explain the negotiation options available throughout the order lifecycle. The negotiations mentioned below refer exclusively to Cancellation Requests made by consumers.

Cancellation Request Proposal

The customer has the option to request the cancellation of an order. This action is only allowed at specific points in the order lifecycle, such as before confirmation, during preparation, when the order is delayed, and after completion.Through the cancellation policy defined by IFood, it is verified whether it is allowed to initiate a negotiation through the Negotiation Platform for a given Cancellation Request before actually canceling it.

How does it work?

When a Negotiation is initiated, the order is not canceled immediately; instead, the partner is given the opportunity to evaluate the cancellation request.Step 1: The customer requests to cancel the order.Step 2: The cancellation engine identifies the need to open a Negotiation with the Partner before completing the Cancellation.Step 3: The Negotiation Flow is initiated.Step 4: The partner receives a HANDSHAKE_DISPUTE event containing relevant information, such as comments and photos, that highlight the reason for the cancellation request.Step 5: After evaluating the Negotiation, the partner has the option to ACCEPT, REJECT, and PROPOSE REFUND through the provided endpoints.

AttentionIt is important to note that if the partner does not respond to the Dispute within the time period specified in the HANDSHAKE_DISPUTE event using the expiresAt attribute, the transaction will be processed automatically and may be accepted or rejected, according to the information contained in the timeoutAction attribute, also available in the HANDSHAKE_DISPUTE event.

Total Cancellation

For Cancellation Request scenarios (After Completion, During Preparation, and Delayed Delivery), before the cancellation is effective, a negotiation will be initiated on the Trading Platform, giving the Partner the opportunity to Accept or Reject the customer's request.In this negotiation scenario, when a customer expresses their intention to cancel an order, the Partner, through the polling mechanism, will receive a HANDSHAKE_DISPUTE event representing a Dispute.To respond to the Dispute represented by the HANDSHAKE_DISPUTE event, the partner must use the following endpoints:

/accept - To ACCEPT the cancellation request
/reject - To REJECT the cancellation request

After a successful request, the Trading Platform will process the request asynchronously. At the next polling check, the partner will receive the following events:

HANDSHAKE_SETTLEMENT
CANCELLED or CANCELLATION_REQUEST_FAILED

TimeoutIf the HANDSHAKE_DISPUTE event is not responded to within the established timeframe, an automatic action is triggered. This will result in the generation of a HANDSHAKE_SETTLEMENT event with the EXPIRED status, and the trade will be closed.

The maximum time limit to respond to a proposal is defined by the expiresAt attribute.
The automatic action to be taken is described by the timeoutAction attribute.

For more details on the automatic response in the event of a timeout, see the Timeout section.

Sequence DiagramTrade execution sequence for a Cancellation Request executed by the Trading Platform for the During Preparation, Delayed Delivery, and After Completion scenarios.

After Completion

In the case of a cancellation request After Completion, before the cancellation is effective, a negotiation will be initiated between the Client and Partner, giving the Partner the opportunity to accept or reject the client's request.In this type of cancellation, the partner will receive the client's justification and images demonstrating the problem.Example of events that will be received:HANDSHAKE_DISPUTE

{ 
"id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
"orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"code":"HSD", 
"fullcode":"HANDSHAKE_DISPUTE", 
"merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"createdAt":"2023-06-23T13:09:06.287636Z", 
"metadata":{ 
"disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
"action":"CANCELLATION", 
"handshakeType":"AFTER_DELIVERY", 
"handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
"timeoutAction":"REJECT_CANCELLATION", 
"metadata":{ 
"evidence":[ 
{ 
"url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
"contentType":"image/jpg" 
} 
] 
}, 
"alternatives":null, 
"message":"order placed: straws Order received: orange cake", 
"expiresAt":"2023-06-23T13:15:06.287636Z", 
"createdAt":"2023-06-23T13:06:50.448434Z" 
}, 
"receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY
timeoutAction	REJECT_CANCELLATION or ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENT

{ 
"id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
"orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"code":"HSS", 
"fullcode":"HANDSHAKE_SETTLEMENT", 
"merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"createdAt":"2023-06-23T13:09:06.287636Z", 
"metadata":{
"disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83",
"status":"REJECTED",
"reason":"Reason for not accepting the Dispute",
"selectedDisputeAlternative":null,
"createdAt":"2023-06-23T13:06:50.448434Z"
},
"receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED or REJECTED

During Preparation

In the cancellation request, during Preparation, before the cancellation is effective, a negotiation will be created in the handshake proposal, giving the Partner the opportunity to Accept or Reject the customer's request.In this type of cancellation, the Partner will only receive the customer's justification.Example of events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"PREPARATION_TIME", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "metadata":null, 
    "disputeAlternatives":null, 
    "message":"Horário de entrega muito tarde", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	PREPARATION_TIME
timeoutAction	REJECT_CANCELLATION or ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "id":"3216ded9-bdee-4440-8c73-b5488e8b1f83", 
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED or REJECTED

Late Delivery

In the case of a cancellation request due to Delivery Delay, a negotiation will be created in the handshake proposal before the cancellation is effective, giving the Partner the opportunity to Accept or Reject the customer's request.In this type of cancellation, the Partner will only receive a justification from the customer.Examples of events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"DELAY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"ACCEPT_CANCELLATION", 
    "metadata":null, 
    "disputeAlternatives":null, 
    "message":"Handshake por atraso", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	DELAY
timeoutAction	REJECT_CANCELLATION or ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENT

{ 
"id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
"orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"code":"HSS", 
"fullcode":"HANDSHAKE_SETTLEMENT", 
"merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
"createdAt":"2023-06-23T13:09:06.287636Z", 
"metadata":{
"disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83",
"status":"REJECTED",
"reason":"Reason for not accepting the proposal",
"selectedDisputeAlternative":null,
"createdAt":"2023-06-23T13:06:50.448434Z"
},
"receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED or REJECTED

Total with Refund Proposal

In Cancellation Request with Refund Proposal scenarios, before the cancellation is completed, a negotiation will be initiated on the Trading Platform, allowing the Partner to ACCEPT, REJECT, and PROPOSE REFUND, with the aim of avoiding a total cancellation and, consequently, financial losses.In this negotiation context, when a Customer expresses their intention to cancel an order, the Partner, through the polling mechanism, will receive a HANDSHAKE_DISPUTE event representing a Dispute.The partner will identify that the Dispute has the Refund Proposal option by checking the alternatives attribute. If it is filled in, the refund proposal can be submitted.To respond to this Dispute, the Partner can use the following endpoints:

/accept: To ACCEPT the cancellation request.
/reject: To REJECT the cancellation request.
/alternative: To send a monetary amount as a refund counterproposal to the Customer, aiming to resolve the situation and avoid order cancellation.

ACCEPT or REJECT EndpointsIf the partner executes the "accept" or "reject" option, no proposal will be sent to the Client, and the negotiation will be terminated.ALTERNATIVE EndpointIf the partner makes a request to the alternative endpoint, the Client will be notified and can accept or reject the counterproposal. After processing this endpoint, the partner will receive a HANDSHAKE_SETTLEMENT event, formalizing the monetary amount sent. This event does not require any additional action and must await the client's response.After the client responds to the refund proposal, regardless of the response, the partner will receive a new HANDSHAKE_SETTLEMENT event informing the Client of the decision.

The maximum time limit to respond to a proposal is defined by the expiresAt attribute.
The automatic action to be taken is described by the timeoutAction attribute.

For more details on the automatic response in case of a timeout, see the Timeout section.

Flow executed without a Refund Proposal

If the partner does not make a refund proposal, the flow will end with the cancellation being accepted or rejected.Sequence DiagramSequence Diagram of a Full Cancellation Request Proposal executed by the Trading Platform.

Example of events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY
timeoutAction	REJECT_CANCELLATION or ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED or REJECTED

Flow executed with Refund Proposal

If the partner makes a refund proposal through the alternative endpoint, the client will receive the proposal made by the partner. After the client responds to the counterproposal, the Partner will receive the HANDSHAKE_SETTLEMENT event, informing and formalizing the Client's decision.Sequence DiagramSequence Diagram of a Full Cancellation Request Proposal with a Refund Proposal executed by the Trading Platform.

Examples of events that will be received:HANDSHAKE_DISPUTEEvent received with the refund proposal option. Generated after using the endpointalternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "amount": {
            "value": "2312",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY
timeoutAction	REJECT_CANCELLATION or ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENTWhen the Dispute is responded to through the alternative endpoint, a HANDSHAKE_SETTLEMENT event will be generated formalizing the refund proposal sent to the customer.

{
   "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
   "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "code":"HSS", 
   "fullcode":"HANDSHAKE_SETTLEMENT", 
   "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "createdAt":"2023-06-23T13:09:06.287636Z", 
   "metadata":{
      "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
      "status":"ALTERNATIVE_REPLIED", 
      "reason":"Razão por não aceitar a proposta", 
      "selectedDisputeAlternative":{
         "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
         "type":"REFUND",
         "metadata": {
            "amount": {
              "value": "2312",
              "currency": "BRL"
            }
        }
      }, 
      "createdAt":"2023-06-23T13:06:50.448434Z"
   }, 
   "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ALTERNATIVE_REPLIED

HANDSHAKE_SETTLEMENTWhen the Dispute is responded to by the customer, a HANDSHAKE_SETTLEMENT Event will be generated, formalizing and informing the customer's response to the refund proposal made by the partner.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED or REJECTED

Negotiation for Delayed Delivery

In this negotiation context, for a full cancellation request due to delay, before the cancellation is effective, a negotiation will be initiated on the Handshake platform, giving the Partner the opportunity to accept the cancellation or propose a new delivery time to the customer.Thus, the objective of this negotiation is to prevent the customer from canceling the order due to delay by offering a new delivery time proposed by the partner.When a customer expresses their intention to cancel an order, the partner, through the polling mechanism, will receive a HANDSHAKE_DISPUTE event representing a Dispute.To respond to this Dispute, the partner must use the following endpoints:

/accept: To ACCEPT the cancellation request.
/alternative: To negotiate a new delivery time for the order.

This flow will not enable the option to decline the cancellation. In other words, in this scenario, the store must either accept the cancellation or propose a new delivery time. If the partner indicates that they wish to decline the cancellation, they will receive an error from the cancellation negotiation API.

ACCEPT EndpointIf the partner executes the "accept" option, no proposal will be sent to the Customer, the negotiation will be closed, and the order will be canceled.ALTERNATIVE EndpointIf the partner makes a request to the alternative endpoint, the Customer will be notified and can accept or reject the order delay negotiation. After processing this endpoint, the partner will receive a HANDSHAKE_SETTLEMENT event, specifying the number of minutes to be added to the delivery time and the reason for this. This event does not require any additional action and must await the client's response.After the client responds to the delivery delay negotiation, regardless of the response, the partner will receive a new HANDSHAKE_SETTLEMENT event informing the client's decision, that is, whether or not the client agreed to wait for the negotiated delivery time.ENDPOINT REJECTYou will receive the following error:

HTTP Status	Description	Cause
400 Bad Request	Cancellation requests with delay negotiation cannot be rejected.	During cancellation with delay negotiation, the REJECT endpoint cannot be used.

Body

{
  "code":"CANCELLATION_WHILE_NEGOTIATION_TIME_CANNOT_BE_REJECTED", 
  "message":"Cancellation while negotiation time cannot be rejected"
}

The maximum time limit to respond to a proposal is defined by the expiresAt attribute.
The automatic action to be executed is described by the timeoutAction attribute.

For more details on the automatic response in case of a timeout, see the Timeout section.

Flow executed without Delay Negotiation

If the partner does not make a refund proposal, the flow will end with the acceptance of the cancellation request.It is worth noting that in this scenario, it is necessary to provide a reason for accepting the cancellation, as described here.Sequence DiagramSequence Diagram of a Full Cancellation Request Proposal executed by the Trading Platform.

Example of events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"CANCELLATION", 
    "handshakeType":"DELAY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ],
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ]
    }, 
    "message":"pedido veio errado", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY
timeoutAction	REJECT_CANCELLATION ou ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "reason":"OTHER_REASONS",
    "detailReason": "This is your detail reason, it is optional",
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED

Flow executed with Delay Negotiation

If the partner makes a delay negotiation through the alternative endpoint, the client will receive the proposal made by the partner. After the client responds to the delay negotiation, the Partner will receive the HANDSHAKE_SETTLEMENT event informing and formalizing the client's decision.Sequence DiagramSequence Diagram of a Full Cancellation Request with Delivery Delay Negotiation executed by the Negotiation Platform.

Examples of events that will be received:HANDSHAKE_DISPUTEEvent received with the option to negotiate a delivery delay.alternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c",
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "code":"HSD",
  "fullcode":"HANDSHAKE_DISPUTE",
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "createdAt":"2023-06-23T13:09:06.287636Z",
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83",
    "action":"CANCELLATION",
    "handshakeType":"DELAY",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "timeoutAction":"REJECT_CANCELLATION",
    "alternatives":[
      {
        "id": "c1f76701-994c-4537-8d54-fb2bc2ee511d",
        "type": "ADDTIONAL_TIME",
        "metadata": {
          "allowedsAdditionalTimeInMinutes": [10, 15, 20, 30],
          "allowedsAdditionalTimeReasons": [
            "HIGH_STORE_DEMAND",
            "OPERATIONAL_ISSUES",
            "LACK_OF_DRIVERS",
            "ORDER_OUT_FOR_DELIVERY",
            "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
          ]
        }
      }
    ],
    "metadata":{
      "acceptCancellationReasons": [
        "HIGH_STORE_DEMAND",
        "STORE_SYSTEM_ISSUES",
        "STORE_INTERNAL_DIFFICULTIES",
        "LACK_OF_DRIVERS",
        "OTHER_REASONS",
        "OPERATIONAL_ISSUES",
        "ORDER_OUT_FOR_DELIVERY"
      ]
    },
    "message":"pedido veio errado",
    "expiresAt":"2023-06-23T13:15:06.287636Z",
    "createdAt":"2023-06-23T13:06:50.448434Z"
  },
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Atributo	Possíveis Valores
handshakeType	DELAY
timeoutAction	REJECT_CANCELLATION ou ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	CANCELLATION

HANDSHAKE_SETTLEMENTWhen the Dispute is responded to through the alternative endpoint, a HANDSHAKE_SETTLEMENT event will be generated, formalizing the negotiation with the number of minutes to be added to the delivery time and the reason for this.

{
   "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
   "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "code":"HSS", 
   "fullcode":"HANDSHAKE_SETTLEMENT", 
   "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
   "createdAt":"2023-06-23T13:09:06.287636Z", 
   "metadata":{
      "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
      "status":"ALTERNATIVE_REPLIED",
      "selectedDisputeAlternative":{
         "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
         "type":"ADDITIONAL_TIME",
         "metadata": {
           "additionalTimeInMinutes":15,
           "additionalTimeReason":"ORDER_OUT_FOR_DELIVERY"
        }
      }, 
      "createdAt":"2023-06-23T13:06:50.448434Z"
   }, 
   "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ALTERNATIVE_REPLIED

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED, REJECTED, EXPIRED

Partial Cancellation

For Partial Cancellation After Completion Request scenarios, before the cancellation is effective, a negotiation will be initiated on the Trading Platform, giving the Partner the opportunity to Accept or Reject the customer's request.In this negotiation scenario, when a customer expresses their intention to cancel an order, the Partner, through the polling mechanism, will receive a HANDSHAKE_DISPUTE event representing a Dispute.To respond to the Dispute represented by the HANDSHAKE_DISPUTE event, the partner must use the following endpoints:

/accept - To ACCEPT the partial cancellation request
/reject - To REJECT the partial cancellation request

After a successful request, the Trading Platform will process the request asynchronously. At the next polling check, the partner will receive the following events:

HANDSHAKE_SETTLEMENT

The maximum time limit to respond to a proposal is defined by the expiresAt attribute.
The automatic action to be taken is described by the timeoutAction attribute.

For more details on the automatic response in case of a timeout, see the Timeout section.

Sequence DiagramExecution sequence of a Negotiation related to a Cancellation Request for Partial Cancellation After Completion scenarios.

Partial Cancellation After Completion

When requesting a Partial Cancellation After Completion, before the cancellation takes effect, a negotiation will begin between the Customer and the Partner. This allows the Partner the opportunity to ACCEPT or REJECT the Customer's request.In this type of negotiation, the Partner will receive the Customer's justification, as well as images showing the items (Item) and/or subitems (GarnishItem) involved in the partial cancellation request.Example of the events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":null, 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY_PARTIALLY
timeoutAction	REJECT_CANCELLATION ou ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	PARTIAL_CANCELLATION

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"REJECTED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":null, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED ou REJECTED

Partial Cancellation with Refund Proposal - Coming Soon

In Partial Cancellation Request with Refund Proposal scenarios, **before the cancellation is completed, a negotiation will be initiated on the Trading Platform, allowing the Partner to ACCEPT, REJECT, and PROPOSE REFUND, in order to avoid partial cancellation and, consequently, financial losses.In this negotiation context, when a Customer expresses the intention to cancel some items in an order, the Partner, through the polling mechanism, will receive a HANDSHAKE_DISPUTE event representing a Dispute.The partner will identify that the Dispute has the Refund Proposal option by checking the alternatives attribute. If it is filled in, the refund proposal can be submitted.To respond to this Dispute, the Partner can use the following endpoints:

/accept: To ACCEPT the partial cancellation request
/reject: To REJECT the partial cancellation request.
/alternative: To send a monetary amount as a refund counterproposal to the Customer, aiming to resolve the situation and avoid cancellation of the partial order.

Accept or Reject EndpointsIf the partner executes the accept or reject option, no proposal will be sent to the Customer, and the transaction will be closed.ALTERNATIVE EndpointIf the partner makes a request to the alternative endpoint, the Client will be notified and can accept or reject the counteroffer. After processing this endpoint, the partner will receive a HANDSHAKE_SETTLEMENT event, formalizing the monetary amount sent. This event does not require any additional action and must wait for the client's response.After the client responds to the refund proposal, regardless of the response, the partner will receive a new HANDSHAKE_SETTLEMENT event informing the Client of the decision made.

The maximum time limit to respond to a proposal is defined by the expiresAt attribute.
The automatic action to be executed is described by the timeoutAction attribute.

For more details on the automatic response in case of a timeout, see the Timeout section.

Flow executed WITHOUT a refund proposal

If the partner does not make a refund proposal, the flow will end with the acceptance or rejection of the cancellation.Sequence DiagramSequence Diagram of a Partial Cancellation Request Proposal.

Examples of events that will be received:HANDSHAKE_DISPUTE

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY_PARTIALLY
timeoutAction	REJECT_CANCELLATION ou ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	PARTIAL_CANCELLATION

HANDSHAKE_SETTLEMENT

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED ou REJECTED

Flow executed with refund proposal

If the partner makes a refund proposal through the alternative endpoint, the client will receive the proposal made by the partner. After the client responds to the counterproposal, the Partner will receive the HANDSHAKE_SETTLEMENT event, informing and formalizing the Client's decision.Sequence DiagramSequence Diagram of a Partial Cancellation Request Proposal executed by the Trading Platform.

Examples of events that will be received:HANDSHAKE_DISPUTEEvent received with the refund proposal option. Generated after using the endpointalternative.

{
  "id":"6d34f8be-7fa6-40f1-877f-8ac564db2a7c", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSD", 
  "fullcode":"HANDSHAKE_DISPUTE", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "action":"PARTIAL_CANCELLATION", 
    "handshakeType":"AFTER_DELIVERY_PARTIALLY", 
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT", 
    "timeoutAction":"REJECT_CANCELLATION", 
    "alternatives":[
      {
        "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
        "type":"REFUND",
        "metadata": {
          "maxAmount": {
            "value": "2400",
            "currency": "BRL"
          }
        }
      }
    ], 
    "metadata":{
      "evidences":[
        {
          "url":"https://merchant-api.ifood.com.br/order/v2.0/orders/{orderId}/cancellationEvidences/{imageId}", 
          "contentType":"image/jpg"
        }
      ], 
      "items":[
        {
          "id":"296b1757-4edf-4a4a-9f03-dfc10d4e907a", 
          "uniqueId":"fe3620ad-c475-4f01-93b9-1ed95907a9ab", 
          "externalCode":"73", 
          "index":1, 
          "quantity":1, 
          "amount":{
            "value":"3890", 
            "currency":"BRL"
          }, 
          "reason":"Não veio a batata, apenas as esfihas"
        }
      ], 
      "garnishItems":[
        {
          "id":"ffa2e2f0-361e-4076-8781-e7c8073326e1", 
          "parentUniqueId":"efe73d06-ccfd-4605-a2a5-1b5b64284b47", 
          "externalCode":"MAI-9601273-601273", 
          "quantity":1, 
          "index":2, 
          "amount":{
            "value":"2650", 
            "currency":"BRL"
          }, 
          "reason":"Revirado e faltando o queijo"
        }
      ]
    }, 
    "message":"Cancelamento parcial", 
    "expiresAt":"2023-06-23T13:15:06.287636Z", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:06:50.628451Z"
}

Attribute	Possible Values
handshakeType	AFTER_DELIVERY_PARTIALLY
timeoutAction	REJECT_CANCELLATION ou ACCEPT_CANCELLATION
handshakeGroup	CUSTOMER_ORDER_SUPPORT
action	PARTIAL_CANCELLATION

HANDSHAKE_SETTLEMENTEvent received with refund proposal option. Generated after using the alternative endpoint.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ALTERNATIVE_REPLIED", 
    "reason":"Razão por não aceitar a proposta", 
    "selectedDisputeAlternative":{
      "id":"54a402d2-5802-4178-b9e0-8c6af1705895", 
      "type":"REFUND", 
      "metadata" : {
        "amount": {
          "value": "2000",
          "currency": "BRL"
        }
      }
    }, 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ALTERNATIVE_REPLIED

HANDSHAKE_SETTLEMENTEvent formalizing the customer's response regarding the refund proposal.

{
  "id":"8290e4ac-8814-46d9-bf38-42d500ce933d", 
  "orderId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "code":"HSS", 
  "fullcode":"HANDSHAKE_SETTLEMENT", 
  "merchantId":"23f5d785-6c76-47d8-bdd0-b3090c90a2a8", 
  "createdAt":"2023-06-23T13:09:06.287636Z", 
  "metadata":{
    "disputeId":"5166ded9-bdee-4440-8c73-b5488e8b1f83", 
    "status":"ACCEPTED", 
    "createdAt":"2023-06-23T13:06:50.448434Z"
  }, 
  "receivedAt":"2023-06-23T13:09:06.287636Z"
}

Attribute	Possible Values
status	ACCEPTED ou REJECTED

Visual Guide

Introduction

This tab was created to provide a detailed visual guide on how to test each cancellation negotiation flow. It is intended to facilitate understanding and execution of the necessary procedures. It is important to note that this document will not include detailed descriptions of each negotiation event data, as this information is already available in the previous tabs.

Cancellation Negotiation After Delivery

Full Cancellation

This negotiation occurs when the customer receives the order and then requests cancellation of the entire order. The merchant will receive the cancellation request and can then accept the cancellation, decline the cancellation, or offer a refund to the customer. Below are the steps to simulate each situation.

Accept the cancellation negotiation

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Customer must request cancellation of the orderTo request order cancellation, open the customer app, open the order, click Help > Order arrived incorrect > Fill out the form selecting all items > Send the information > Select the option "I do not want to receive a refund on my iFood balance".

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant API.

{
  "id":"d74ac331-9e5b-467f-96fe-57c143b9177a",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"6211e666-2fec-4369-b261-5a422c5ef350",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:02:46.921Z",
  "metadata":{
    "action":"CANCELLATION",
    "alternatives":[
      {
        "id":"9945f8f1-03ff-4762-8cfd-0f20db66741d",
        "metadata":{
          "maxAmount":{
            "currency":"BRL",
            "value":"800"
          }
        },
        "type":"REFUND"
      }
    ],
    "createdAt":"2024-04-25T18:02:46.798698Z",
    "disputeId":"0a2d440f-98f3-4919-ac0b-aa5afe8f4135",
    "expiresAt":"2024-04-25T18:09:46.798698Z",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "handshakeType":"AFTER_DELIVERY",
    "message":"Testando testando",
    "metadata":{
      "evidences":[
        {
          "contentType":"image/jpeg",
          "url":"https://merchant-api.ifood.com.br/order/v1.0/orders/6211e666-2fec-4369-b261-5a422c5ef350/cancellationEvidences/4c76b8ea-51db-42d5-806f-1a086753bc4a"
        }
      ]
    },
    "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestPara responder, o merchant pode optar em usar o Gestor de pedidos ou a merchant-api. Seguem exemplos das duas maneiras de interagir com a negociação. Exemplo imagem do Gestor de pedidosExample request for merchant-api
```
curl --location --request POST
'https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/accept' \
--header 'Authorization: Bearer jwt-token' \
--data ''
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"4bf1cd30-e50b-41b8-9827-0ad448d3c700",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"6211e666-2fec-4369-b261-5a422c5ef350",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:03:43.186Z",
  "metadata":{
    "createdAt":"2024-04-25T18:03:43.083117651Z",
    "disputeId":"0a2d440f-98f3-4919-ac0b-aa5afe8f4135",
    "status":"ACCEPTED"
  }
}

Reject cancellation negotiation

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Customer must request cancellation of the order

To request order cancellation, open the customer app, open the order, click Help > Order came wrong > Fill out the form selecting all items > Send the information > Select the option "I do not want to receive a refund on my iFood balance".

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant API.

{
  "id":"41597d87-79f1-4a8b-a66d-d575e0a7ccc2",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:05:24.098Z",
  "metadata":{
    "action":"PARTIAL_CANCELLATION",
    "alternatives":[
      {
        "id":"5154c746-918b-4f85-80b1-3b5a448710bb",
        "metadata":{
          "maxAmount":{
            "currency":"BRL",
            "value":"2080"
          }
        },
        "type":"REFUND"
      }
    ],
    "createdAt":"2024-04-25T19:05:23.953526Z",
    "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
    "expiresAt":"2024-04-25T19:12:23.953526Z",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "handshakeType":"AFTER_DELIVERY_PARTIALLY",
    "metadata":{
      "garnishItems":[
        {
          "amount":{
            "currency":"BRL",
            "value":"300"
          },
          "id":"2bb737bf-1b72-419d-a77d-8047f07dd144",
          "index":0,
          "parentUniqueId":"631839cb-05ca-428b-ba1f-ab1ee7ecc57a",
          "quantity":3,
          "reason":"Testando test"
        }
      ]
    },
    "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager imageExemplo de request para merchant-api
```
curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/reject' \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ "reason": "some reason" }'
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"4bf1cd30-e50b-41b8-9827-0ad448d3c700",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"6211e666-2fec-4369-b261-5a422c5ef350",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:03:43.186Z",
  "metadata":{
      "createdAt":"2024-04-25T18:03:43.083117651Z",
      "disputeId":"0a2d440f-98f3-4919-ac0b-aa5afe8f4135",
      "reason":"teste teste teste",
      "status":"REJECTED"
  }
}

Submit refund proposal

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Customer must request cancellation of the order

To request order cancellation, open the customer app, open the order, click Help > Order came wrong > Fill out the form selecting all items > Send the information > Select the option "I do not want to receive a refund on my iFood balance".

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant API.

{
  "id":"d74ac331-9e5b-467f-96fe-57c143b9177a",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"6211e666-2fec-4369-b261-5a422c5ef350",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:02:46.921Z",
  "metadata":{
      "action":"CANCELLATION",
      "alternatives":[
        {
            "id":"9945f8f1-03ff-4762-8cfd-0f20db66741d",
            "metadata":{
              "maxAmount":{
                  "currency":"BRL",
                  "value":"800"
              }
            },
            "type":"REFUND"
        }
      ],
      "createdAt":"2024-04-25T18:02:46.798698Z",
      "disputeId":"0a2d440f-98f3-4919-ac0b-aa5afe8f4135",
      "expiresAt":"2024-04-25T18:09:46.798698Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"AFTER_DELIVERY",
      "message":"Testando testando",
      "metadata":{
        "evidences":[
            {
              "contentType":"image/jpeg",
              "url":"https://merchant-api.ifood.com.br/order/v1.0/orders/6211e666-2fec-4369-b261-5a422c5ef350/cancellationEvidences/4c76b8ea-51db-42d5-806f-1a086753bc4a"
            }
        ]
      },
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager image

Request example for merchant-api

curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/alternatives/9945f8f1-03ff-4762-8cfd-0f20db66741d' \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ \
        "type": "REFUND", \
        "metadata": { \
        "amount": { \
        "currency": "BRL", \
        "value": "200" \
    }}}'

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"3e561c1f-391f-460d-99c1-4858e43f6fa4",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"98403df8-828b-41e3-a3d1-0c9265e854a6",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:47:26.185Z",
  "metadata":{
      "createdAt":"2024-04-25T18:47:26.047174208Z",
      "disputeId":"d3d271f4-886c-4c75-b6bf-8ee3d1e7708c",
      "selectedDisputeAlternative":{
        "id":"ec7e0d30-c305-4037-8b82-3dca7d9fb0a3",
        "metadata":{
            "amount":{
              "currency":"BRL",
              "value":"200"
            }
        },
        "type":"REFUND"
      },
      "status":"ALTERNATIVE_REPLIED"
  }
}

Finally, the merchant will receive another HANDSHAKE_SETTLEMENT event via polling, informing them of the customer's response—that is, whether the customer accepted, declined, or did not respond to the refund proposal sent by the merchant. In this case, the customer accepted the refund. If the customer does not accept the refund, the metadata status will be REJECTED. If the customer does not respond to the refund proposal, the same metadata will be EXPIRED.
```
{
  "id":"1cba5e42-fe07-45f4-8eed-b3188de5ffeb",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"98403df8-828b-41e3-a3d1-0c9265e854a6",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:50:05.149Z",
  "metadata":{
      "createdAt":"2024-04-25T18:50:05.051587724Z",
      "disputeId":"d145bcc6-b5a3-40a6-b9de-a206ac7b536c",
      "status":"ACCEPTED"
  }
}
```

Partial cancellation

This negotiation occurs when the customer receives the order and then requests to cancel items in the order. The merchant receives the cancellation request and can then accept the cancellation, decline the cancellation, or offer a refund to the customer. Below are the steps to simulate each situation.

Accept cancellation negotiation

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Customer must request cancellation of the order

To request order cancellation, open the customer app, open the order, click Help > Order came wrong > Fill out the form by selecting some items > Send the information > Select the option "I do not want to receive a refund on my iFood balance".

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant API.

{
  "id":"41597d87-79f1-4a8b-a66d-d575e0a7ccc2",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:05:24.098Z",
  "metadata":{
      "action":"PARTIAL_CANCELLATION",
      "alternatives":[
        {
            "id":"5154c746-918b-4f85-80b1-3b5a448710bb",
            "metadata":{
              "maxAmount":{
                  "currency":"BRL",
                  "value":"2080"
              }
            },
            "type":"REFUND"
        }
      ],
      "createdAt":"2024-04-25T19:05:23.953526Z",
      "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
      "expiresAt":"2024-04-25T19:12:23.953526Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"AFTER_DELIVERY_PARTIALLY",
      "metadata":{
        "garnishItems":[
            {
              "amount":{
                  "currency":"BRL",
                  "value":"300"
              },
              "id":"2bb737bf-1b72-419d-a77d-8047f07dd144",
              "index":0,
              "parentUniqueId":"631839cb-05ca-428b-ba1f-ab1ee7ecc57a",
              "quantity":3,
              "reason":"Testando test"
            }
        ]
      },
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager imageRequest example for merchant-api
```
curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/accept' \
    --header 'Authorization: Bearer jwt-token' \
    --data ''
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"7fb701a9-0996-4418-a3dc-8afa55786764",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:06:38.788Z",
  "metadata":{
    "createdAt":"2024-04-25T19:06:38.692323486Z",
    "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
    "status":"ACCEPTED"
  }
}

Reject cancellation negotiation

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Customer must request cancellation of the order

To request order cancellation, open the customer app, open the order, click Help > Order came wrong > Fill out the form by selecting some items > Send the information > Select the option "I do not want to receive a refund on my iFood balance".

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant API.

{
  "id":"41597d87-79f1-4a8b-a66d-d575e0a7ccc2",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:05:24.098Z",
  "metadata":{
      "action":"PARTIAL_CANCELLATION",
      "alternatives":[
        {
            "id":"5154c746-918b-4f85-80b1-3b5a448710bb",
            "metadata":{
              "maxAmount":{
                  "currency":"BRL",
                  "value":"2080"
              }
            },
            "type":"REFUND"
        }
      ],
      "createdAt":"2024-04-25T19:05:23.953526Z",
      "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
      "expiresAt":"2024-04-25T19:12:23.953526Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"AFTER_DELIVERY_PARTIALLY",
      "metadata":{
        "garnishItems":[
            {
              "amount":{
                  "currency":"BRL",
                  "value":"300"
              },
              "id":"2bb737bf-1b72-419d-a77d-8047f07dd144",
              "index":0,
              "parentUniqueId":"631839cb-05ca-428b-ba1f-ab1ee7ecc57a",
              "quantity":3,
              "reason":"Testando test"
            }
        ]
      },
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager imageRequest example for merchant-api
```
curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/reject \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ "reason": "some reason" }'
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"7fb701a9-0996-4418-a3dc-8afa55786764",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:06:38.788Z",
  "metadata":{
      "createdAt":"2024-04-25T19:06:38.692323486Z",
      "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
      "reason":"testando o cancelamento parcial",
      "status":"REJECTED"
  }
}

Submit refund proposal

Create an order
Merchant must confirm and ship the order
Customer must confirm receipt of order

Cliente deve solicitar o cancelamento do pedido

To request an order cancellation, open the customer app, open the order, click Help > Order arrived incorrect > Fill out the form by selecting a few items > Submit the information > Select the option "I don't want to receive a refund to my iFood balance."

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant-api.

{
  "id":"41597d87-79f1-4a8b-a66d-d575e0a7ccc2",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"3c5332ee-0616-44de-bff3-37a40b93f834",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:05:24.098Z",
  "metadata":{
    "action":"PARTIAL_CANCELLATION",
    "alternatives":[
      {
        "id":"5154c746-918b-4f85-80b1-3b5a448710bb",
        "metadata":{
          "maxAmount":{
            "currency":"BRL",
            "value":"2080"
          }
        },
        "type":"REFUND"
      }
    ],
    "createdAt":"2024-04-25T19:05:23.953526Z",
    "disputeId":"9eec04a6-5374-4e20-9713-29926924fbc1",
    "expiresAt":"2024-04-25T19:12:23.953526Z",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "handshakeType":"AFTER_DELIVERY_PARTIALLY",
    "metadata":{
      "garnishItems":[
        {
          "amount":{
            "currency":"BRL",
            "value":"300"
          },
          "id":"2bb737bf-1b72-419d-a77d-8047f07dd144",
          "index":0,
          "parentUniqueId":"631839cb-05ca-428b-ba1f-ab1ee7ecc57a",
          "quantity":3,
          "reason":"Testando test"
        }
      ]
    },
    "timeoutAction":"REJECT_CANCELLATION"
  }
}

Example of a request to the merchant-api

curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2bb737bf-1b72-419d-a77d-8047f07dd144/reject \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ \
        "reason": "some reason" \
    }'

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"4163c287-9855-47a6-a3d9-8712d8b698fe",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"f8b78870-bb5c-4bc9-9de5-bda7dcf3a0ca",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:28:46.065Z",
  "metadata":{
      "createdAt":"2024-04-25T19:28:45.942401249Z",
      "disputeId":"2bb737bf-1b72-419d-a77d-8047f07dd144",
      "selectedDisputeAlternative":{
        "id":"5154c746-918b-4f85-80b1-3b5a448710bb",
        "metadata":{
            "amount":{
              "currency":"BRL",
              "value":"300"
            }
        },
        "type":"REFUND"
      },
      "status":"ALTERNATIVE_REPLIED"
  }
}

Por fim, o merchant receberá via polling outro evento de HANDSHAKE_SETTLEMENT informando sobre a resposta do cliente, ou seja, se o cliente aceitou, recusou ou não respondeu a proposta de reembolso enviada pelo merchant. Neste caso o cliente aceitou o reembolso. Caso o cliente não aceite o reembolso o metadata status terá o valor REJECTED. Caso o cliente não responda a proposta de reembolso, o mesmo metadata terá o valor EXPIRED.

{
  "id":"1cba5e42-fe07-45f4-8eed-b3188de5ffeb",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"98403df8-828b-41e3-a3d1-0c9265e854a6",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T18:50:05.149Z",
  "metadata":{
      "createdAt":"2024-04-25T18:50:05.051587724Z",
      "disputeId":"d145bcc6-b5a3-40a6-b9de-a206ac7b536c",
      "status":"ACCEPTED"
  }
}

Cancellation Negotiation During Preparation

This negotiation occurs when the customer requests a cancellation while the merchant is preparing the order. The merchant will receive the cancellation request and can either accept or decline the cancellation. Below are the steps to simulate each situation.

Accept the cancellation negotiation

Create an order
The merchant must confirm the order

The customer must request the order cancellation

To request an order cancellation, open the customer app, open the order, click Help > I accidentally purchased > Cancel order > Fill out the form and submit.

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant-api.

{
  "id":"1d115926-c439-4cfb-a1df-f8fd4385f2aa",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"f98c70e9-7dc0-4a07-abd1-c8c33e1cd48c",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:46:10.350Z",
  "metadata":{
    "action":"CANCELLATION",
    "createdAt":"2024-04-25T19:46:10.252389Z",
    "disputeId":"b1cab1e3-d4fd-4808-b9eb-5789b04870f2",
    "expiresAt":"2024-04-25T19:51:10.252389Z",
    "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
    "handshakeType":"PREPARATION_TIME",
    "message":"Teste teste teste",
    "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager imageExample of a request to the merchant-api
```
curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/b1cab1e3-d4fd-4808-b9eb-5789b04870f2/accept' \
    --header 'Authorization: Bearer jwt-token' \
    --data ''
```

Após a resposta do merchant ficará disponível via polling na merchant-api um evento chamado HANDSHAKE_SETTLEMENT representando a opção que o merchant escolheu.

{
  "id":"12060fb5-9ce0-4c60-9bfa-cacc524fe0f3",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"f98c70e9-7dc0-4a07-abd1-c8c33e1cd48c",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:46:47.576Z",
  "metadata":{
      "createdAt":"2024-04-25T19:46:47.474850698Z",
      "disputeId":"b1cab1e3-d4fd-4808-b9eb-5789b04870f2",
      "status":"ACCEPTED"
  }
}

Accept the cancellation negotiation

Create an order
Merchant must confirm the order

Customer must request order cancellation

To request order cancellation, open the customer app, open the order, click Help > I accidentally purchased > Cancel order > Fill out the form and submit.

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will open a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant-api.

{
  "id":"1d115926-c439-4cfb-a1df-f8fd4385f2aa",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"f98c70e9-7dc0-4a07-abd1-c8c33e1cd48c",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:46:10.350Z",
  "metadata":{
      "action":"CANCELLATION",
      "createdAt":"2024-04-25T19:46:10.252389Z",
      "disputeId":"b1cab1e3-d4fd-4808-b9eb-5789b04870f2",
      "expiresAt":"2024-04-25T19:51:10.252389Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"PREPARATION_TIME",
      "message":"Teste teste teste",
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to the cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager image

Example of a request to the merchant-api

curl --location --request POST \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/b1cab1e3-d4fd-4808-b9eb-5789b04870f2/reject \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ \
        "reason": "some reason" \
    }'

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"12060fb5-9ce0-4c60-9bfa-cacc524fe0f3",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"f98c70e9-7dc0-4a07-abd1-c8c33e1cd48c",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T19:46:47.576Z",
  "metadata":{
      "createdAt":"2024-04-25T19:46:47.474850698Z",
      "disputeId":"b1cab1e3-d4fd-4808-b9eb-5789b04870f2",
      "status":"REJECTED"
  }
}

Cancellation Negotiation Due to Delay

This negotiation occurs when a customer requests a cancellation due to an order being late. The merchant will receive the cancellation request and can either accept the cancellation or negotiate a new delivery time. Below are the steps to simulate each situation.This feature is currently in the rollout phase, so for the merchant to receive this negotiation, they must have the LC_OPS_ORDER_LATE_MARKETPLACE_CHAT_HANDSHAKE_ENABLED configuration set to S.

Accept the cancellation negotiation

Create an order
Merchant must confirm the order
Wait for the order to be late

Customer must request order cancellation

To request an order cancellation, open the customer app, open the order, and click I need help. A chat will open. The customer will receive a message, stating that the order hasn't arrived yet. Afterward, the customer will receive another message with a "I want a new estimate" button. Click the button.

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant-api.

{
  "id":"59c778f3-6e2a-476c-8d44-32c94cc64f6d",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"66a772fb-899e-4b60-9c18-7580d68c8c27",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T20:31:49.529Z",
  "metadata":{
      "action":"CANCELLATION",
      "alternatives":[
        {
            "id":"db7c4043-2bd3-4f0a-aff5-0dc2f3f76bf8",
            "metadata":{
              "allowedsAdditionalTimeInMinutes":[
                  10,
                  15,
                  20,
                  30
              ],
              "allowedsAdditionalTimeReasons":[
                  "HIGH_STORE_DEMAND",
                  "OPERATIONAL_ISSUES",
                  "LACK_OF_DRIVERS",
                  "ORDER_OUT_FOR_DELIVERY",
                  "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
              ]
            },
            "type":"ADDITIONAL_TIME"
        }
      ],
      "createdAt":"2024-04-25T20:31:49.420595Z",
      "disputeId":"b6a7fe78-34c8-4c11-ac81-060a0de8961f",
      "expiresAt":"2024-04-25T20:36:49.420595Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"DELAY",
      "message":"Handshake Order Late",
      "metadata":{
        "acceptCancellationReasons":[
            "HIGH_STORE_DEMAND",
            "STORE_SYSTEM_ISSUES",
            "STORE_INTERNAL_DIFFICULTIES",
            "LACK_OF_DRIVERS",
            "OTHER_REASONS"
        ]
      },
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to cancellation requestTo respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager image - Click "Order will no longer be delivered"Example: Enter the reason using the checkbox and, if desired, you can specify a little more about why the order will no longer be delivered.Example request to merchant-apiIn this specific transaction, when accepting the cancellation, the merchant must state why they are accepting the cancellation, providing one of the reasons listed in the HANDSHAKE_DISPUTE event in the acceptCancellationReasons metadata.
```
curl --location \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/2097e3ef-1e0e-46ad-a083-5b39cd615df7/accept' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ \
        "reason": "STORE_SYSTEM_ISSUES" \
    }'
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"5d76a147-c7f1-4952-81df-13dd5d1f215d",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"66a772fb-899e-4b60-9c18-7580d68c8c27",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T20:32:39.448Z",
  "metadata":{
      "createdAt":"2024-04-25T20:32:39.335193155Z",
      "disputeId":"b6a7fe78-34c8-4c11-ac81-060a0de8961f",
      "reason":"STORE_SYSTEM_ISSUES",
      "status":"ACCEPTED"
  }
}

Negotiate New Delivery Time

Create an order
Merchant must confirm the order
Wait for the order to be delayed

Customer must request order cancellation

To request order cancellation, open the customer app, open the order, and click I need help. A chat will open. The customer will receive a message stating that the order hasn't arrived yet. Afterward, the customer will receive another message with a "I want a new estimate" button. Click the button.

At this point, the cancellation platform will receive the cancellation request and, after validating the cancellation policies, will initiate a negotiation with the restaurant. This negotiation is represented by the HANDSHAKE_DISPUTE event. This event will be available for polling via the merchant-api.

{
  "id":"59c778f3-6e2a-476c-8d44-32c94cc64f6d",
  "code":"HSD",
  "fullCode":"HANDSHAKE_DISPUTE",
  "orderId":"66a772fb-899e-4b60-9c18-7580d68c8c27",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T20:31:49.529Z",
  "metadata":{
      "action":"CANCELLATION",
      "alternatives":[
        {
            "id":"db7c4043-2bd3-4f0a-aff5-0dc2f3f76bf8",
            "metadata":{
              "allowedsAdditionalTimeInMinutes":[
                  10,
                  15,
                  20,
                  30
              ],
              "allowedsAdditionalTimeReasons":[
                  "HIGH_STORE_DEMAND",
                  "OPERATIONAL_ISSUES",
                  "LACK_OF_DRIVERS",
                  "ORDER_OUT_FOR_DELIVERY",
                  "DRIVER_IS_ALREADY_AT_THE_ADDRESS"
              ]
            },
            "type":"ADDITIONAL_TIME"
        }
      ],
      "createdAt":"2024-04-25T20:31:49.420595Z",
      "disputeId":"b6a7fe78-34c8-4c11-ac81-060a0de8961f",
      "expiresAt":"2024-04-25T20:36:49.420595Z",
      "handshakeGroup":"CUSTOMER_ORDER_SUPPORT",
      "handshakeType":"DELAY",
      "message":"Handshake Order Late",
      "metadata":{
        "acceptCancellationReasons":[
            "HIGH_STORE_DEMAND",
            "STORE_SYSTEM_ISSUES",
            "STORE_INTERNAL_DIFFICULTIES",
            "LACK_OF_DRIVERS",
            "OTHER_REASONS"
        ]
      },
      "timeoutAction":"REJECT_CANCELLATION"
  }
}

Merchant must respond to the cancellation request.To respond, the merchant can choose to use the Order Manager or the merchant-api. Below are examples of both ways to interact with the transaction. Example of an Order Manager image Fill out the form, selecting the delay time and the reason for the delay. Click "Update delivery estimate."Example of a request to the merchant-api In this specific transaction, when proposing a new delivery time, the merchant must indicate the delay time and the reason for the delay. The options the merchant can choose for this are listed in the HANDSHAKE_DISPUTE event, in the metadata alternatives.metadata.allowedsAdditionalTimeInMinutes and alternatives.metadata.allowedsAdditionalTimeReasons respectively.
```
curl --location \
    'https://merchant-api.ifood.com.br/order/v1.0/disputes/c95c9885-a0ac-447e-863c-158f97dffd08/alternatives/97c6529f-6d40-4a0a-a6c2-43b64590c81b' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer jwt-token' \
    --data '{ \
        "type": "ADDITIONAL_TIME", \
        "metadata": { \
            "additionalTimeInMinutes": 30, \
            "additionalTimeReason":"OPERATIONAL_ISSUES" \
        } \
    }'
```

After the merchant's response, an event called HANDSHAKE_SETTLEMENT representing the option the merchant chose will be available via polling in the merchant-api.

{
  "id":"a803ca50-f452-43c7-bd90-6ba52367a7e9",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"062ea86a-c71e-4285-a991-aad49538bf68",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T20:22:39.298Z",
  "metadata":{
      "createdAt":"2024-04-25T20:22:39.154324166Z",
      "disputeId":"c993fb45-ef7d-495a-9561-b1f03f5712d7",
      "selectedDisputeAlternative":{
        "id":"8052879f-a311-45b3-bf75-78a90b5728ab",
        "metadata":{
            "additionalTimeMinutes":10,
            "additionalTimeReason":"HIGH_STORE_DEMAND"
        },
        "type":"ADDITIONAL_TIME"
      },
      "status":"ALTERNATIVE_REPLIED"
  }
}

Finally, the merchant will receive another HANDSHAKE_SETTLEMENT event via polling, informing them of the customer's response—that is, whether the customer accepted, declined, or did not respond to the refund proposal sent by the merchant. In this case, the customer accepted the refund. If the customer does not accept the refund, the metadata status will be REJECTED. If the customer does not respond to the refund proposal, the same metadata will be EXPIRED.
```
{
  "id":"dae8bc7e-efbb-473f-b444-9024c5ca9a56",
  "code":"HSS",
  "fullCode":"HANDSHAKE_SETTLEMENT",
  "orderId":"062ea86a-c71e-4285-a991-aad49538bf68",
  "merchantId":"d1a3bc50-6103-49e0-afeb-b619b753fe69",
  "createdAt":"2024-04-25T20:22:49.030Z",
  "metadata":{
      "createdAt":"2024-04-25T20:22:48.923096307Z",
      "disputeId":"6cb058e7-7b17-4415-a957-24038ac522ec",
      "status":"ACCEPTED"
  }
}
```

How to view cancellation evidence images

Not every transaction will have cancellation evidence images. When there is cancellation evidence, simply make a GET request using the link in the metadata.evidences[X].url field. Below is a code example that retrieves cancellation evidence.

<!DOCTYPE html>
<html lang="pt">
   <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Imagem do Servidor</title>
   </head>
   <body>
      <img id="imagemServidor" src="" alt="Imagem do Servidor" style="max-width: 100%; height:
         auto;">
      <script>
         const urlImagem =
         "https://merchant-api.ifood.com.br/order/v1.0/orders/abeff264-bf8b-472d-a6ad-11fea0096253/canc
         ellationEvidences/89422573-3b50-421d-a0f4-051642e75f70";
         const opcoesFetch = {
         method: 'GET',
         headers: {
         'Authorization': 'Bearer jwt-token'
         }
         };
         fetch(urlImagem, opcoesFetch)
         .then(response => {
         if (!response.ok) {
         throw new Error('Falha ao buscar a imagem: ' + response.statusText);
         }
         return response.blob();
         })
         .then(blob => {
         const urlBlob = URL.createObjectURL(blob);
         document.getElementById('imagemServidor').src = urlBlob;
         })
         .catch(error => {
         console.error('Erro:', error);
         });
      </script>
   </body>
</html>