Manage risks and liabilities/
Manage disputes and chargebacks/
Test dispute workflows/
Simulate test scenarios

Simulate test scenarios

DocsCurrent

Last updated: Jul 31st, 8:01pm

Simulate common test scenarios to check if your Disputes API integration correctly handles internal disputes, chargebacks, bank transfers, merchant responses, appeals, and related webhooks.

Internal disputes

The buyer disputes the transaction with PayPal. Transaction can be done through card, bank, digital wallets, and other supported payment methods.

Test data conditions (applies to all tests):

Test name Description Expected input Dispute APIs to use Expected outcome
Dispute NO HOLD, MERCHANT WINS CASE Open the dispute.

PayPal does not hold the money in the merchant's account.

The merchant provides evidence.

The case resolves in the merchant's favor.		 The buyer opens a dispute in the PayPal wallet.

The merchant provides the requested evidence.		 Create: POST v1/customer/disputes/

Provide evidence: POST v1/customer/disputes/{id}/provide-evidence

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission
    (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The merchant's account balance remains unchanged.
Dispute WITH HOLD, MERCHANT WINS CASE Open the dispute.

PayPal holds the money in the merchant account.

The merchant provides evidence.

The case resolves in the merchant's favor and the hold releases.		 The buyer opens a dispute in the PayPal wallet.

The merchant provides the requested evidence.		 Create: POST v1/customer/disputes/

Provide evidence: POST v1/customer/disputes/{id}/provide-evidence

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission
    (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

PayPal releases the hold on merchant account.
Dispute NO HOLD, MERCHANT LOSES CASE (no data), NO SELLER PROTECTION, DISPUTE FEE is charged Open the dispute.

PayPal does not hold the money in the merchant account.

The merchant does not provide evidence.

The case resolves in the buyer's favor.		 The buyer opens a dispute in the PayPal wallet.

The merchant does not provide the requested evidence.		 Create: POST v1/customer/disputes/

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission
    (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The case resolves in the buyer's favor. The transaction is not eligible for Seller Protection.

PayPal debits the merchant account.


Chargeback

The buyer disputes a card transaction with their card issuer.

Test data conditions (applies to all tests):

  • Mastercard: Reason code - 4853
  • Visa: Reason code - C2
  • For test conditions where a temporary hold applies, the hold is placed and released when the case is resolved in the merchant's favor.
Test name Description Expected input Dispute APIs to use Expected outcome
Chargeback WITH PROVISIONAL CREDIT, MERCHANT WINS CASE Open the chargeback.

The merchant provides evidence.

The case resolves in the merchant's favor.		 The buyer opens a chargeback with the issuer.

The merchant provides the requested evidence.		 Provide evidence: POST v1/customer/disputes/{id}/provide-evidence

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission
    (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The merchant's account balance remains unchanged.
Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT WINS CASE Open the chargeback

There is no hold on the merchant account.

The merchant provides evidence.

The case resolves in the merchant's favor.		 The buyer opens a chargeback with the issuer.

The merchant provides evidence.		 Provide evidence: POST v1/customer/disputes/{id}/provide-evidence

Partner receives the webhooks for: 

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The merchant's account balance remains unchanged.
Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data) Open the chargeback.

There is no hold on the merchant's account.

The merchant does not provide evidence.

The case resolves in the buyer's favor.		 The buyer opens a chargeback with the issuer.

The merchant does not provide the requested evidence.		 none

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The case resolves in the buyer's favor.

PayPal debits the merchant's account.
Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data) Open the chargeback

There is no hold on the merchant account.

The merchant does not provide evidence.

The case resolves in the buyer's favor.		 The buyer opens the chargeback with the issuer.

The merchant does not provide evidence.		 none

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

The case resolves in the buyer's favor.

PayPal debits the merchant's account.
Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (adjudication) Open the chargeback.

There is no hold on the merchant account.

The merchant provides evidence.

The case resolves in the buyer's favor and the merchant is debited.		 The buyer opens a chargeback with the issuer.

The merchant provides evidence.		 Provide evidence: POST v1/customer/disputes/{id}/provide-evidence
 

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The case adjudicates in the buyer's favor after evidence review.

PayPal debits the merchant's account.

Bank transfer (ACH return)

The buyer disputes a bank funded transaction with their bank.

Test data conditions (applies to all tests):

  • Use the correct transaction amount to simulate the test transaction.
  • Set up configurations to determine partner vs merchant liability for the dispute amount and dispute fee amount.
Test name Description Expected
input		 Test data conditions Dispute APIs to use Expected outcome
ACH - SPP Ineligible - Buyer Favor Create a member bank and capture unauthorized iACH transaction dispute in the sandbox.

The case closes automatically in the buyer's favor without asking for merchant response, because the transaction is not SPP eligible. 		none Use an SPP ineligible transaction for dispute creation. none

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation and resolution.

PayPal debits the merchant or partner for the dispute amount and dispute fee.
ACH - SPP Eligible - No merchant response - Buyer Favor Create a member bank and capture unauthorized iACH transaction dispute in the sandbox.

The case moves to merchant response phase.

The merchant does not respond within the 10-day SLA.

The case resolves in the buyer's favor.		 Does not provide a merchant response within the SLA timeframe. Use an SPP eligible transaction for dispute creation. none

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

PayPal debits the merchant or partner for the dispute amount and dispute fee.
ACH - SPP Eligible - merchant responds - Merchant Favor Create a member bank and capture unauthorized iACH transaction dispute in the sandbox.

The case moves to merchant response phase.

The merchant responds within the 10-day SLA.

The case resolves in the merchant's favor.		 Provides a response with evidence type as OTHER when the case moves to merchant response phase. Use an SPP eligible transaction for dispute creation. Provide evidence: POST v1/customer/disputes/{id}/provide-evidence

Partner receives the webhooks for:

  • Case creation (CUSTOMER.DISPUTE.CREATED).
  • Merchant response for evidence submission (CUSTOMER.DISPUTE.UPDATED).
  • Case resolution (CUSTOMER.DISPUTE.RESOLVED).

The merchant receives emails for case creation, response request, and resolution.

PayPal holds the transactions during case creation and releases the hold when the case resolves in the merchant's favor.

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.


Appeal dispute

When PayPal adjudicates a case against a party, the buyer or merchant may be eligible to appeal the decision. PayPal uses predefined rules to determine appeal eligibility.

To test appeals:

  • Create a buyer account with a primary email address that includes allowappeal. Disputes created with this account will trigger:
    • The seller appeal workflow if the merchant is found liable.
    • The buyer appeal workflow if the buyer is found liable.
  • Each party can submit only one appeal per case.

To simulate cases where appeals are not allowed, create a buyer account with a primary email address that includes noappeal.

The merchant can appeal the dispute in the following ways:

Appeal with PROOF_OF_FULFILLMENT

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

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute.
  3. Resolve the case against the merchant. Call settle dispute with adjudication_outcome as BUYER_FAVOR.
  4. The client calls Show dispute details.
  5. Check whether appeal dispute is allowed in HATEOAS links.
  6. 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 merchant can appeal the dispute by providing refund information for all reason codes.

Test steps PayPal actions Client actions
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute.
  3. Resolve the case against the merchant. Call settle dispute with adjudication_outcome as BUYER_FAVOR.
  4. The client calls Show dispute details.
  5. Check whether appeal dispute is allowed in HATEOAS links.
  6. 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
  1. Log in to the PayPal resolution center using buyer credentials.
  2. Open a dispute.
  3. Resolve the case against the merchant. Call settle dispute with adjudication_outcome as BUYER_FAVOR.
  4. The client calls Show dispute details.
  5. Check whether appeal dispute is allowed in HATEOAS links.
  6. The client calls the appeal dispute API with evidence type as OTHER.

Each API call succeeds.

Each API call succeeds.

Webhook test cases

To test Disputes webhooks, you need to wait a few minutes after creating the dispute for the actions to become available.

You can test for the following webhooks:

You can also test for duplicated webhooks and identify them using the unique ID in the webhook payload.

Terminology used:

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

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.

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