Disputes acceptance test criteria

DocsCurrent

Last updated: Nov 20th, 10:51am

Learn about the acceptance test criteria to test your Disputes API integration. For concepts, see Disputes Overview.

Terminology used:

SNAD: Significantly Not As Described

INR: Item Not Received

To perform various actions as a buyer to test the updated webhooks, wait a few minutes after creation for the action to be available.

Dispute created webhook

Inquiry Stage

PayPal SNAD case

The customer chooses a completed transaction to open an SNAD case.

Test steps	PayPal actions	Client actions
Merchant opted in the dispute phase. Log in to the PayPal resolution center using buyer credentials. Open a SNAD case.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns the dispute details with the `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` reason. The dispute lifecycle stage is `INQUIRY`.

PayPal INR case

The customer chooses a completed transaction to open an INR case.

Test steps	PayPal actions	Client actions
Merchant opted in the dispute phase. Log in to the PayPal resolution center using buyer credentials. Open an INR case.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns dispute details with the `MERCHANDISE_OR_SERVICE_NOT_RECEIVED` reason. The dispute lifecycle stage is `INQUIRY`.

Claim stage

PayPal SNAD case

The customer chooses a completed transaction to open an SNAD case.

Test steps	PayPal actions	Client actions
Merchant opts out of dispute phase. Log in to the PayPal resolution center. Open an SNAD case.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns dispute details with `MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED` reason. Dispute lifecycle stage is `CHARGEBACK`.

PayPal INR case

The customer chooses a completed transaction to open an INR case.

Test steps	PayPal actions	Client actions
Merchant opts out of dispute phase. Log in to the PayPal resolution center. Open an INR case.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns dispute details with the `MERCHANDISE_OR_SERVICE_NOT_RECEIVED` reason. Dispute lifecycle stage is `CHARGEBACK`.

PayPal unauthorized dispute case

The customer chooses a completed transaction to open an unauthorized case.

Note: When testing unauthorized disputes, the buyer and merchant receive different dispute IDs. For merchants, the format and identifiers of the notifications stay the same as those of other dispute types.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center. Open an unauthorized case.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns dispute details with the `UNAUTHORISED` reason.

PayPal transaction error dispute case

Six different reason codes are applicable for transaction error disputes.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center. Open a case with the `CREDIT_NOT_PROCESSED`, `DUPLICATE_TRANSACTION`, `INCORRECT_AMOUNT`, `PAYMENT_BY_OTHER_MEANS`, `CANCELED_RECURRING_BILLING`, or `OTHER` reason code on the completed transaction.	The action succeeds and the dispute created webhook is sent.	The client receives the `CUSTOMER.DISPUTE.CREATED` webhook. The show dispute details call returns dispute details with `CREDIT_NOT_PROCESSED`, `DUPLICATE_TRANSACTION`, `INCORRECT_AMOUNT`, `PAYMENT_BY_OTHER_MEANS`, `CANCELED_RECURRING_BILLING`, or `OTHER` reason code.

Duplicate dispute creation for a transaction is blocked

The customer cannot open a duplicate dispute on a transaction that already has an existing dispute. Even after the dispute case is closed, the customer cannot open a dispute on the same transaction again.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center. using buyer credentials. Duplicate dispute creation for a transaction is blocked, set `adjudication_outcome` to `BUYER_FAVOR`. Check whether the buyer can open a dispute for the transaction.	The customer cannot open a duplicate dispute on the same transaction.	The customer cannot open a duplicate dispute on the same transaction.

Dispute updated webhook

Inquiry stage

Customer sends a message to the merchant

The customer sends message to the merchant for INR or SNAD dispute in the INQUIRY phase.

Test steps	PayPal actions	Client actions
Merchant opts into the dispute phase. Log in to the PayPal resolution center using buyer credentials. Open an INR or SNAD case. Send a message through the resolution center.	PayPal sends dispute updated webhook with the message details	The client receives the `CUSTOMER.DISPUTE.UPDATED` webhook and updates its internal system accordingly.

Claim stage

Buyer provides return tracking information

The merchant accepts the dispute claim and provides the buyer with the return shipping address. The buyer then returns the item and updates the return tracking number in the Resolution Center.

Test steps	PayPal actions	Client actions
Merchant opts out of the dispute phase. Log in to the PayPal resolution center using buyer credentials. Open a SNAD dispute on the PayPal side. Client calls accept claim with return shipping address. The customer provides the tracking number through the PayPal Resolution Center. The dispute updated webhook is triggered.	PayPal sends the dispute updated webhook.	The client receives the `CUSTOMER.DISPUTE.UPDATED` webhook. The return tracking information is available in the Show dispute details API response.

Change reason

The customer updates the INR reason code to SNAD or Unauthorized.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute INR case on the PayPal side. Click on Change case type and update the reason to SNAD/UNAUTHORISED.	PayPal sends the dispute updated webhook with new reason code.	The client receives the `CUSTOMER.DISPUTE.UPDATED` webhook from PayPal and updates the reason code accordingly.

Dispute resolved webhook

Customer cancels dispute

The customer cancels a dispute in resolution center.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute. Click on Close this case and cancel the dispute.	The action succeeds and PayPal sends the dispute resolved webhook.	The client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook.

Dispute case close (customer wins)

The PayPal agent settles the case in the customer's favor.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials Open a dispute. Call settle dispute in the sandbox. To settle the case in the customer's favour, set `adjudication_outcome` to `BUYER_FAVOR`.	The action succeeds and PayPal sends the dispute resolved webhook.	The client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook.

Dispute case close (merchant wins)

The PayPal agent settles the case in the merchant's favor.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute. Call settle dispute in the sandbox. To settle the case in the customer's favour, set `adjudication_outcome` to `SELLER_FAVOR`.	The action succeeds and PayPal sends the dispute resolved webhook.	The client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook.

Identify unique webhook through webhook ID

Client can use webhook ID in dispute webhooks to identify a duplicated webhook.

Test steps	PayPal actions	Client actions
Open a dispute through PayPal resolution center. Listen to the dispute webhooks - `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.RESOLVED`, `CUSTOMER.DISPUTE.UPDATE`.		The unique ID is available in the webhook payload. The client can identify the webhook uniquely through the webhook ID.

Response due date and HATEOAS links

To determine whether to call provide evidence, accept claim, make offer, acknowledge item return or appeal API, the client must check whether the corresponding HATEOAS link is available in the links section of the Show dispute details response. The client can check the seller_response_due_date to determine the deadline by which the merchant must respond to the dispute.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open an INR dispute. Call Show dispute details. Validate that the case is waiting for merchant response.	Each API call succeeds.	The status of the case is `WAITING_FOR_SELLER_RESPONSE`. The `seller_response_due_date` is populated. The links section contains the links for the APIs.

Merchant response – Inquiry Stage

The merchant can send a message to the buyer, provide evidence, make an offer, or accept the claim on a dispute in the inquiry phase.

Prerequisite: The merchant should have opted in for the dispute phase.

Send Message

PayPal SNAD case

The customer chooses a completed transaction to open a SNAD case. The merchant can reply to the customer through the "send message" option for that dispute.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Check if send message action is allowed in HATEOAS links. The client calls Send message.	Each API call succeeds and the merchant message is visible in show dispute details.	Each API call succeeds and the merchant message is visible in Show dispute details.

PayPal INR case

The customer chooses a completed transaction to open an INR case. Merchants can reply to the customer through the "send message" option for that dispute.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a INR case. The client calls Show dispute details. Check if send message action is allowed in HATEOAS links. The client calls Send message.	Each API call succeeds and merchant message is visible in show dispute details and message is visible in the Resolution Center.	Each API call succeeds and the merchant message is visible in Show dispute details.

Make offer

Each API call succeeds and the merchant message is visible in Show dispute details.

Refund with return – SNAD case

The customer chooses a completed transaction to open a SNAD case. The merchant can make an offer to the customer to return the item for a refund.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Verify that make offer action is allowed in HATEOAS links. The client calls Make offer and shares the amount the merchant is willing to refund to the customer as `seller_offered_amount` and offer type as `REFUND_WITH_RETURN` together with the the shipping address.	Each API call succeeds and `seller_offered_amount` and offer type is visible in Show dispute details.	Each API call succeeds and `seller_offered_amount` is visible in Show dispute details.

Refund with replacement – SNAD case

The customer selects a completed transaction to open a SNAD case. The merchant can offer the customer a replacement item along with a refund.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Verify that make offer action is allowed in HATEOAS links. The client calls make-offer and shares the amount the merchant is willing to refund to the customer as `seller_offered_amount` and offer type as `REFUND_WITH_REPLACEMENT`.	Each API call succeeds and `seller_offered_amount` and offer type is visible in Show dispute details.	Each API call succeeds and `seller_offered_amount` is visible in Show dispute details.

Replacement without refund – SNAD case

IThe customer chooses a completed transaction to open a SNAD case. The merchant can make an offer to the customer to replace the item to amicably resolve the case.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Verify that make offer action is allowed in HATEOAS links. The client calls make-offer and shares the amount the merchant is willing to refund to the customer as `seller_offered_amount` and offer type as `REPLACEMENT_WITHOUT_REFUND`.	Each API call succeeds and returns expected response.	Each API call succeeds and `seller_offered_amount` is visible in Show dispute details.

PayPal INR case

The customer chooses a completed transaction to open an INR case. Merchants can make an offer to the customer to amicably resolve the dispute

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open an INR case. The client calls Show dispute details. Verify that make offer action is allowed in HATEOAS links. The client calls make-offer and shares the amount the merchant is willing to refund to the customer as `seller_offered_amount` and offer type as `REFUND`.	Each API call succeeds and `seller_offered_amount` and offer type is visible in the Show dispute details.	Each API call succeeds and `seller_offered_amount` is visible in Show dispute details.

Acknowledge item return

If the merchant offers a refund with the return of the item and the buyer accepts it, the buyer can upload the return tracking information. After the buyer completes this step, the merchant has the option to acknowledge receipt of the item.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Verify that make offer action is allowed in HATEOAS links. The client calls make-offer and shares the amount the merchant is willing to refund to the customer as `seller_offered_amount` and offer type as `REFUND_WITH_RETURN` along with the return shipping address. Log in to the PayPal resolution center using buyer credentials. Accept the merchant's offer. Add the return tracking information. The client calls Show dispute details. Verify that acknowledge item return action is allowed in HATEOAS links. The client calls Acknowledge returned item API.	Each API call succeeds.	Each API call succeeds.

Provide Evidence

PROOF_OF_FULFILLMENT evidence

PayPal enables client to provide tracking information for INR cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open an INR case. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `PROOF_OF_FULFILLMENT` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence api with evidence type as `PROOF_OF_FULFILLMENT` along with the tracking information.	Each API call succeeds.	Each API call succeeds.

PROOF_OF_REFUND evidence

PayPal helps the client to provide refund information for the dispute cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open the dispute on the PayPal side. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `PROOF_OF_REFUND` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence api with evidence type as `PROOF_OF_REFUND` along with the refund ids.	Each API call succeeds.	Each API call succeeds.

OTHER evidence

PayPal helps the client to provide multiple photos, materials, and files as evidence for the cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open the dispute on the PayPal side. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `OTHER` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence API with evidence type as `OTHER` along with the notes or documents.	Each API call succeeds.	Each API call succeeds.

Accept claim

Client accepts to refund the requested dispute amount to customer

If the client decides not to dispute the case, they can accept the claim to refund the customer.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open the dispute on the PayPal side. The client calls Show dispute details. Verify whether accept claim action is allowed. Call the accept claim API.	Each API call succeeds and returns the expected response.	Each API call succeeds and returns the expected response. The client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook. A refund amount is available in the outcome.

Escalate

PayPal SNAD case

The customer chooses a completed transaction to open a SNAD case. The merchant escalates the case because they cannot reach an amicable resolution with the customer.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD case. The client calls Show dispute details. Verify that escalate action is allowed in HATEOAS links. The client calls escalates and shares the merchant's notes with PayPal for further action.	Each API call succeeds, and the dispute lifecycle stage is updated from `INQUIRY` to `CHARGEBACK` and is visible in show dispute details. The system also triggers `CUSTOMER.DISPUTE.UPDATED`.	Each API call succeeds, and the dispute lifecycle stage is updated from `INQUIRY` to `CHARGEBACK` and is visible in show dispute details. The client receives the `CUSTOMER.DISPUTE.UPDATED` webhook.

PayPal INR case

The customer chooses a completed transaction to open an INR case. The merchant escalates the case as they cannot reach an amicable resolution with the customer.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open an INR case. The client calls Show dispute details. Verify that escalate action is allowed in HATEOAS links. The client calls escalates and shares the merchant's notes with PayPal for further action.	Each API call succeeds, and the dispute lifecycle stage is updated from `INQUIRY` to `CHARGEBACK` and is visible in show dispute details. The system also triggers `CUSTOMER.DISPUTE.UPDATED`.	Each API call succeeds, and the dispute lifecycle stage is updated from `INQUIRY` to `CHARGEBACK` and is visible in show dispute details. The client receives the `CUSTOMER.DISPUTE.UPDATED` webhook.

Merchant response - Claim stage

The merchant can provide evidence or accept a claim on a dispute in the Claim phase.

Prerequisite: The merchant should have opted out of the dispute phase.

Provide evidence

PROOF_OF_FULFILLMENT evidence

PayPal helps the client to provide tracking information for INR cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open an INR case. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `PROOF_OF_FULFILLMENT` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence API with evidence type as `PROOF_OF_FULFILLMENT` along with the tracking information.	Each API call succeeds.	Each API call succeeds.

PROOF_OF_REFUND evidence

PayPal helps the client to provide refund information for the cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute on the PayPal side. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `PROOF_OF_REFUND` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence API with evidence type as `PROOF_OF_REFUND` along with the refund ids. .	Each API call succeeds.	Each API call succeeds.

OTHER evidence

PayPal helps the client to provide multiple photos, materials, and files as evidence for the cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute on the PayPal side. The client calls Show dispute details. Verify whether provide evidence link is available and if the evidences section contains evidence type `OTHER` with source as `REQUESTED_FROM_SELLER`. Call the provide evidence API with evidence type as `OTHER` along with the notes or documents.	Each API call succeeds.	Each API call succeeds.

Accept claim

Client accepts to refund requested dispute amount to customer

If the client decides not to dispute the case, the client can accept the claim to refund the customer.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute on the PayPal side. The client calls Show dispute details. Check whether the accept claim link is available in the links section. The client calls accept claim.	Each API call succeeds and returns the expected response.	Each API call succeeds and returns the expected response. The client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook. A refund amount is available in the outcome.

Client accepts claim to refund customer if customer returns item to specified address

If the case is SNAD, the client can refund the customer for returning the item.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD dispute. The client calls show dispute details. Check whether the accept claim link is available in the links section. The client calls accept claim with return shipping address. The customer provides the tracking number through the PayPal Resolution Center. The CUSTOMER.DISPUTE.UPDATED is triggered. To get tracking information, the client calls show dispute details.	The tracking information is returned in show dispute details.	The client can get tracking information in show dispute details and update the case.

Client agrees to refund customer a different amount from the disputed amount (partial refund)

If the case is SNAD, the client can refund the customer for an amount less than the customer's requested refund for returning the item.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a SNAD dispute. The client calls Show dispute details. Check whether the accept claim link is available in the links section. The client calls accept claim with an explicit refund amount and return shipping address.	Each API call succeeds and returns the expected response.	Each API call succeeds. If the refund amount is greater than or equal to the customer-requested disputed amount, the case is resolved, and the client receives the `CUSTOMER.DISPUTE.RESOLVED` webhook. If the amount is less than the customer-requested dispute amount, it triggers an email to a customer seeking their consent in the resolution center.

Appeal dispute

Appeal with PROOF_OF_FULFILLMENT

If the case is decided against the merchant, the client can appeal the dispute by providing fulfillment information for INR, Unauthorized, or other cases.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute. Resolve the case against the merchant. Call settle dispute with `adjudication_outcome` as `BUYER_FAVOR`. The client calls Show dispute details. Check whether appeal dispute is allowed in HATEOAS links. The client calls the appeal dispute API with evidence type as `PROOF_OF_FULFILLMENT` along with the tracking information.	Each API call succeeds.	Each API call succeeds.

Appeal with PROOF_OF_REFUND

If the case is decided against the merchant, the client can appeal the dispute by providing refund information for all reason codes.

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute. Resolve the case against the merchant. Call settle dispute with `adjudication_outcome` as `BUYER_FAVOR`. The client calls Show dispute details. Check whether appeal dispute is allowed in HATEOAS links. The client calls the appeal dispute API with evidence type as `PROOF_OF_REFUND` along with the refund ids.	Each API call succeeds.	Each API call succeeds.

Appeal with OTHER evidence

Test steps	PayPal actions	Client actions
Log in to the PayPal resolution center using buyer credentials. Open a dispute. Resolve the case against the merchant. Call settle dispute with `adjudication_outcome` as `BUYER_FAVOR`. The client calls Show dispute details. Check whether appeal dispute is allowed in HATEOAS links. The client calls the appeal dispute API with evidence type as `OTHER`.	Each API call succeeds.	Each API call succeeds.