Multiparty/
Multiparty/
Manage disputes and chargebacks/
Test integration - acceptance criteria

Test integration – acceptance criteria

DocsCURRENT

Last updated: Jul 31st, 7:45pm

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

The merchant can test the following scenarios:

PayPal SNAD case

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

Test steps PayPal actions Client actions
  1. Merchant opted in the dispute phase.
  2. Log in to the PayPal resolution center using buyer credentials.
  3. Open a SNAD case.

The action succeeds and the dispute created webhook is sent.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. The show dispute details call returns the dispute details with the MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED reason.
  3. 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
  1. Merchant opted in the dispute phase.
  2. Log in to the PayPal resolution center using buyer credentials.
  3. Open an INR case.

The action succeeds and the dispute created webhook is sent.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. The show dispute details call returns dispute details with the MERCHANDISE_OR_SERVICE_NOT_RECEIVED reason.
  3. The dispute lifecycle stage is INQUIRY.

Claim stage

The merchant can test the following scenarios:

PayPal SNAD case

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

Test steps PayPal actions Client actions
  1. Merchant opts out of dispute phase.
  2. Log in to the PayPal resolution center.
  3. Open an SNAD case.

The action succeeds and the dispute created webhook is sent.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. The show dispute details call returns dispute details with MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED reason.
  3. 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
  1. Merchant opts out of dispute phase.
  2. Log in to the PayPal resolution center.
  3. Open an INR case.

The action succeeds and the dispute created webhook is sent.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. The show dispute details call returns dispute details with the MERCHANDISE_OR_SERVICE_NOT_RECEIVED reason.
  3. 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
  1. Log in to the PayPal resolution center.
  2. Open an unauthorized case.

The action succeeds and the dispute created webhook is sent.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. 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
  1. Log in to the PayPal resolution center.
  2. 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.
  1. The client receives the CUSTOMER.DISPUTE.CREATED webhook.
  2. 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
  1. Log in to the PayPal resolution center.
    2. using buyer credentials.
  2. Duplicate dispute creation for a transaction is blocked, set adjudication_outcome to BUYER_FAVOR.
  3. 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

Buyer sends a message to the merchant

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

Test steps PayPal actions Client actions
  1. Merchant opts into the dispute phase.
  2. Log in to the PayPal resolution center using buyer credentials.
  3. Open an INR or SNAD case.
  4. 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

The merchant can test the following scenarios:

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
  1. Merchant opts out of the dispute phase.
  2. Log in to the PayPal resolution center using buyer credentials.
  3. Open a SNAD dispute on the PayPal side.
  4. Client calls accept claim with return shipping address.
  5. The buyer provides the tracking number through the PayPal Resolution Center.
  6. The dispute updated webhook is triggered.

PayPal sends the dispute updated webhook.
  1. The client receives the CUSTOMER.DISPUTE.UPDATED webhook.
  2. The return tracking information is available in the Show dispute details API response.

Buyer changes reason

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute INR case on the PayPal side.
  3. 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

The merchant can test the following scenarios:

Buyer cancels dispute

The buyer cancels a dispute in resolution center.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute.
  3. 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 (buyer wins)

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials
  2. Open a dispute.
  3. Call settle dispute in the sandbox. To settle the case in the buyer'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
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute.
  3. Call settle dispute in the sandbox. To settle the case in the buyer'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
  1. Open a dispute through PayPal resolution center.
  2. 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.

Merchant response

The merchant must check the available HATEOAS links in the links array of Show dispute details to determine which actions are available:

To determine the response due date, the merchant can check the seller_response_due_date.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR dispute.
  3. Call Show dispute details.
  4. 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.

Inquiry stage

In the inquiry phase, the merchant can

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

Terminology used:

  • SNAD: Significantly Not As Described
  • INR: Item Not Received

Send Message

The merchant can send a message in the following scenarios:

PayPal SNAD case

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Check if send message action is allowed in HATEOAS links.
  5. 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 buyer chooses a completed transaction to open an INR case. Merchants can reply to the buyer through the "send message" option for that dispute.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR case.
  3. The client calls Show dispute details.
  4. Check if send message action is allowed in HATEOAS links.
  5. 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

The merchant can make an offer in the following ways:

The merchant can further acknowledge an item return when the buyer returns the item and uploads the tracking information.

Refund with return – SNAD case

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Verify that make offer action is allowed in HATEOAS links.
  5. The client calls Make offer and shares the amount the merchant is willing to refund to the buyer 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 buyer selects a completed transaction to open a SNAD case. The merchant can offer the buyer a replacement item along with a refund.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Verify that make offer action is allowed in HATEOAS links.
  5. The client calls make-offer and shares the amount the merchant is willing to refund to the buyer 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

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Verify that make offer action is allowed in HATEOAS links.
  5. The client calls make-offer and shares the amount the merchant is willing to refund to the buyer 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.

Refund without replacement - PayPal INR case

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR case.
  3. The client calls Show dispute details.
  4. Verify that make offer action is allowed in HATEOAS links.
  5. The client calls make-offer and shares the amount the merchant is willing to refund to the buyer 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
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Verify that make offer action is allowed in HATEOAS links.
  5. The client calls make-offer and shares the amount the merchant is willing to refund to the buyer as seller_offered_amount and offer type as REFUND_WITH_RETURN along with the return shipping address.
  6. Log in to the PayPal resolution center using buyer credentials.
  7. Accept the merchant's offer.
  8. Add the return tracking information.
  9. The client calls Show dispute details.
  10. Verify that acknowledge item return action is allowed in HATEOAS links.
  11. The client calls Acknowledge returned item API.

Each API call succeeds.

Each API call succeeds.

Provide Evidence

The merchant can provide the following types of evidence:

PROOF_OF_FULFILLMENT evidence

PayPal enables merchant to provide tracking information for INR cases.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR case.
  3. The client calls Show dispute details.
  4. Verify whether provide evidence link is available and if the evidences section contains evidence type PROOF_OF_FULFILLMENT with source as REQUESTED_FROM_SELLER.
  5. 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 merchant to provide refund information for the dispute cases.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open the dispute on the PayPal side.
  3. The client calls Show dispute details.
  4. Verify whether provide evidence link is available and if the evidences section contains evidence type PROOF_OF_REFUND with source as REQUESTED_FROM_SELLER.
  5. 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 merchant to provide multiple photos, materials, and files as evidence for the cases.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open the dispute on the PayPal side.
  3. The client calls Show dispute details.
  4. Verify whether provide evidence link is available and if the evidences section contains evidence type OTHER with source as REQUESTED_FROM_SELLER.
  5. 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

Refund the dispute amount

If the merchant decides not to dispute the case, they can accept the claim to refund the buyer.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open the dispute on the PayPal side.
  3. The client calls Show dispute details.
  4. Verify whether accept claim action is allowed.
  5. 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

The merchant can escalate the dispute in the following scenarios:

PayPal SNAD case

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD case.
  3. The client calls Show dispute details.
  4. Verify that escalate action is allowed in HATEOAS links.
  5. 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 triggersCUSTOMER.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 buyer chooses a completed transaction to open an INR case. The merchant escalates the case as they cannot reach an amicable resolution with the buyer.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR case.
  3. The client calls Show dispute details.
  4. Verify that escalate action is allowed in HATEOAS links.
  5. 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.

Claim stage

In the claim phase, the merchant can

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

Terminology used:

  • SNAD: Significantly Not As Described
  • INR: Item Not Received

Provide evidence

The merchant can provide the following types of evidence:

PROOF_OF_FULFILLMENT evidence

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open an INR case.
  3. The client calls Show dispute details.
  4. Verify whether provide evidence link is available and if the evidences section contains evidence type PROOF_OF_FULFILLMENT with source as REQUESTED_FROM_SELLER.
  5. 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 merchant to provide refund information for the cases.

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

Each API call succeeds.

Each API call succeeds.

OTHER evidence

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute on the PayPal side.
  3. The client calls Show dispute details.
  4. Verify whether provide evidence link is available and if the evidences section contains evidence type OTHER with source as REQUESTED_FROM_SELLER.
  5. 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

The merchant can accept a claim in the following ways:

Refund the dispute amount

If the merchant decides not to dispute the case, the merchant can accept the claim to refund the buyer.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute on the PayPal side.
  3. The client calls Show dispute details.
  4. Check whether the accept claim link is available in the links section.
  5. 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.

Refund the dispute amount on item return to a specified address

If the case is SNAD, the merchant can refund the buyer for returning the item.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD dispute.
  3. The client calls show dispute details.
  4. Check whether the accept claim link is available in the links section.
  5. The client calls accept claim with return shipping address.
  6. The buyer provides the tracking number through the PayPal Resolution Center.
  7. The CUSTOMER.DISPUTE.UPDATED is triggered.
  8. 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.

Partial refund

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a SNAD dispute.
  3. The client calls Show dispute details.
  4. Check whether the accept claim link is available in the links section.
  5. 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 buyer-requested disputed amount, the case is resolved, and the client receives the CUSTOMER.DISPUTE.RESOLVED webhook.
If the amount is less than the buyer-requested dispute amount, it triggers an email to a buyer seeking their consent in the resolution center.


ReferencePayPal.comPrivacyCookiesSupportLegalContact

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more