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
Before going live, you can use the PayPal sandbox environment to test the Disputes API integration. This ensures it works as expected and meets all business and technical requirements.
Before testing dispute responses for your integration, you need to simulate buyer actions to create the disputes and transactions in the sandbox environment.
To create a transaction in the sandbox environment, do these steps:
A successful call returns a 201 Created response and an HATEOAS link for the dispute. Use the dispute ID from the HATEOAS link to perform subsequent tests on the dispute.
A successful call returns a 201 Created response and a dispute ID. Use the dispute ID to perform subsequent tests on the dispute.
You can change the reason for a dispute using this endpoint in the sandbox environment. This allows you to test how your integration handles changes to dispute reasons.
This is a sandbox-only endpoint. You cannot use it to change dispute reasons in the live environment.
A successful call returns a 200 OK response and an HATEOAS link for the dispute.
Accept a merchant's offer to resolve a dispute by ID. PayPal automatically refunds the proposed amount to the customer.
Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/accept-offer endpoint. Include the following parameter:
Parameter, Description, Action
Parameter
Description
Action
note string
The customer's notes about accepting the offer. PayPal can view these notes, but the merchant cannot.
Pass a note if needed.
Path parameter: id is the dispute_id returned in the Create dispute response.
curl --request POST \ --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/accept-offer \ --header 'Authorization: Bearer ACCESS-TOKEN' \ --header 'Content-Type: application/json' \ --header 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \ --data '{ "note": "I am ok with the refund offered."}'
A successful call returns an HTTP 200 OK status code and a HATEOAS link to the dispute. If money movement for the offer is delayed due to internal reasons, the call returns an HTTP 202 Accepted status code instead.
The customer denies a merchant's offer to resolve a dispute, by ID.
Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/deny-offer endpoint. Include the following parameter:
Parameter, Description, Action
Parameter
Description
Action
note Required, string
The customer's notes about the denial of the offer. PayPal can view these notes, but the merchant cannot.
Pass the reason for denying the offer.
Path parameter: id is the dispute_id returned in the Create dispute response.
This is a sandbox-only endpoint. You cannot use it to settle disputes in the live environment.
Settle a dispute in the customer's or merchant's favor to complete end-to-end dispute resolution testing in the sandbox. Before you make this call, confirm that the dispute status is UNDER_REVIEW and the adjudicate link is available in the HATEOAS links of the show dispute details response.
To make this call, the dispute status must be UNDER_REVIEW and the adjudicate link must be available in the HATEOAS links of the show dispute details response.
Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/adjudicate endpoint. Include the following parameter:
Parameter, Description, Action
Parameter
Description
Action
adjudication_outcome Required, string
The outcome of the adjudication.
Possible values: BUYER_FAVOR, SELLER_FAVOR
Pass the outcome to indicate whether the dispute is resolved in the customer's or merchant's favor.
Path parameter: id is the dispute_id returned in the Create dispute response.
A successful call returns an HTTP 200 OK status code and a HATEOAS link to the dispute.
This is a sandbox-only endpoint. You cannot use it to update dispute statuses in the live environment.
Updates the status of a dispute, by ID, from UNDER_REVIEW to either WAITING_FOR_BUYER_RESPONSE or WAITING_FOR_SELLER_RESPONSE. This status change enables either the customer or merchant to submit evidence for the dispute.
To make this call, the dispute status must be UNDER_REVIEW and the require-evidence link must be available in the HATEOAS links of the show dispute details response.
Use a valid access token and make a POST call to the /v1/customer/disputes/{id}/require-evidence endpoint. Include the following parameter:
Parameter, Description, Action
Parameter
Description
Action
action Required, string
Indicates whether the status change enables the customer or merchant to submit evidence.
Possible values: BUYER_EVIDENCE, SELLER_EVIDENCE
Pass BUYER_EVIDENCE to set the status to WAITING_FOR_BUYER_RESPONSE, or SELLER_EVIDENCE to set it to WAITING_FOR_SELLER_RESPONSE.
Path parameter: id is the dispute_id returned in the Create dispute response.
You can use the scenarios in this section to test how your integration handles disputes and chargebacks in the sandbox environment.
You can test internal disputes by creating a dispute for a transaction with PayPal. The dispute can be for payments made using a card, bank account, digital wallet, or other supported payment methods.
Test data condition: Use OTHER as the evidence type when you provide evidence.
Scenario, Description, Test steps, Expected outcome
Scenario
Description
Test steps
Expected outcome
Dispute NO HOLD, MERCHANT WINS CASE
The buyer creates a dispute for a transaction where PayPal does not hold the money in the merchant's account.
The merchant provides evidence and the case resolves in the merchant's favor.
You can test and determine how to respond to disputes using different scenarios. This ensures that your integration correctly handles the merchant actions during the dispute process.
The API returns a 200 OK response. It includes status, seller_response_due_date, and links parameters that help you respond appropriately within the timeframe.
You can use the procedures in this section to test dispute response handling during the inquiry stage.
You can test sending a message to the buyer during the inquiry stage of a dispute. For example, when a buyer creates an INR or SNAD case for a completed transaction, you can send a message to the buyer directly and help resolve the issue before it escalates.
offer_amount: Set the amount that you are willing to refund the buyer.
offer_type: Set the value as REFUND_WITH_RETURN.
return_shipping_address: Pass the shipping address for returning the item.
The API returns a 200 OK response. You can retrieve the dispute details and check the offer.seller_offered_amount and offer.offer_type parameters in the response.
For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item along with a refund.
offer_amount: Set the amount that you are willing to refund the buyer.
offer_type: Set the value as REFUND_WITH_REPLACEMENT.
The API returns a 200 OK response. You can retrieve the dispute details and check the offer.seller_offered_amount and offer.offer_type parameters in the response.
For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item without a refund.
offer_amount: Set the amount that you are willing to refund the buyer.
offer_type: Set the value as REFUND.
The API returns a 200 OK response. You can retrieve the dispute details and check the offer.seller_offered_amount and offer.offer_type parameters in the response.
For the actions involving return, you can acknowledge returned item when the buyer returns the item and uploads the tracking information.
You can test offering a refund with the return of the item, accept it as a buyer and upload the return tracking information. After this, the acknowledge return item option will be available for you.
The API returns a 200 OK response. You can retrieve the dispute details and check the offer.seller_offered_amount, offer.offer_type, and acknowledgement_type parameters in the response.
You can test providing evidence for these evidence types. This section applies to INR cases only.
You can test the PROOF_OF_FULFILLMENT evidence type by providing tracking information for the INR cases.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as PROOF_OF_FULFILLMENT and source as REQUESTED_FROM_SELLER.
evidence_type: Set the value as PROOF_OF_FULFILLMENT.
evidence_info.tracking_info: Pass the tracking information for the item.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, and evidence_info.tracking_info parameters within the evidences object in the response.
You can test the PROOF_OF_REFUND evidence type by providing refund details for the INR cases.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as PROOF_OF_REFUND and source as REQUESTED_FROM_SELLER.
evidence_info.refund_ids: Pass the refund ID for the item.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, and evidence_info.refund_ids parameters within the evidences object in the response.
You can test the OTHER evidence type by providing notes or documents (including photos and files) for the INR cases.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as OTHER and source as REQUESTED_FROM_SELLER.
notes: Pass the additional evidence details as notes.
documents: Pass the document details.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, notes, and documents parameters within the evidences object in the response.
You can test accepting the claim and refunding the buyer when you choose not to dispute the case.
Note: Merchant must have sufficient funds to issue a refund.
Check if the accept claim action is available in the HATEOAS links.
Accept the claim with the accept_claim_type parameter value as REFUND.
The API returns a 200 OK response. You can retrieve the dispute details and check the dispute_outcome object in the response. The CUSTOMER.DISPUTE.RESOLVED webhook notification with the refund details is sent to the buyer.
You can test escalating the dispute to a claim to simulate cases where you cannot reach an amicable resolution with the buyer.
The API returns a 200 OK response. You can retrieve the dispute details and check the dispute_life_cycle_stage parameter value is updated from INQUIRY to CHARGEBACK. The system also triggers the CUSTOMER.DISPUTE.UPDATED webhook.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as PROOF_OF_FULFILLMENT and source as REQUESTED_FROM_SELLER.
evidence_type: Set the value as PROOF_OF_FULFILLMENT.
evidence_info.tracking_info: Pass the tracking information for the item.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, and evidence_info.tracking_info parameters within the evidences object in the response.
You can test the PROOF_OF_REFUND evidence type by providing refund details for the INR or SNAD cases.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as PROOF_OF_REFUND and source as REQUESTED_FROM_SELLER.
evidence_info.refund_ids: Pass the refund ID for the item.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, and evidence_info.refund_ids parameters within the evidences object in the response.
You can test the OTHER evidence type by providing notes or documents (including photos and files) for the INR or SNAD cases.
Check if the provide evidence is available in the HATEOAS links and if the evidences object contains evidence_type as OTHER and source as REQUESTED_FROM_SELLER.
notes: Pass the additional evidence details as notes.
documents: Pass the document details.
The API returns a 200 OK response. You can retrieve the dispute details and check the evidence_type, source, notes, and documents parameters within the evidences object in the response.
You can test accepting the claim and refunding the buyer if you choose to resolve the case using these accept claim types.
Note: Merchant must have sufficient funds to issue a refund.
The test procedure to refund the dispute amount is identical in the inquiry and claim stages. For detailed information, see Accept claim.
You can test accepting the claim for a SNAD case and refunding the buyer after they return the item to a specified address.
return_shipping_address: Pass the shipping address for returning the item.
accept_claim_type: Set the value as REFUND_WITH_RETURN.
Buyer: In the PayPal Resolution Center, view the dispute details and provide the tracking information for the returned item.
The system triggers the CUSTOMER.DISPUTE.UPDATED webhook. You can retrieve the dispute details and check the response parameters to get the tracking information and update the case.
You can test accepting the claim and providing a partial refund (amount less than the buyer-requested refund) to the buyer for a INR or SNAD cases.
If the refund amount is greater than or equal to the buyer-requested refund amount, the case is resolved, and you receive the CUSTOMER.DISPUTE.RESOLVED webhook notification.
If the amount is less than the buyer-requested refund amount, it triggers an email to the buyer for their consent in the Resolution Center.
You can test offering a refund with the return of the item, accept it as a buyer and upload the return tracking information. After this, the acknowledge return item option will be available for you.
The API returns a 200 OK response. You can retrieve the dispute details and check the offer.seller_offered_amount, offer.offer_type, and acknowledgement_type parameters in the response.
When PayPal adjudicates a case against a party, you or the buyer 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 (for example, [email protected]). The disputes created with this account will trigger:
The seller appeal workflow if you are 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 for a buyer, create a buyer account with a primary email address that includes noappeal (for example, [email protected]).
You can appeal the case and provide evidence using these evidence types.
If the case is resolved in the buyer's favor, you can appeal by providing the fulfillment information for INR, unauthorized, or other cases.
If the evidences object contains the evidence_type and evidence_info.refund_ids parameter values you provided.
If the status and dispute_life_cycle_stage parameter values are UNDER_REVIEW and PRE_ARBITRATION respectively.
If the case is resolved in the buyer's favor, you can appeal by providing notes or documents. You can use the OTHER evidence type if the requested evidence is not covered by the PROOF_OF_FULFILLMENT and PROOF_OF_REFUND evidence types.
To enable Accelerated Response for a dispute, include the value ACCELERATED_RESPONSE_ENABLED in the notes field under evidences when submitting your create_dispute API request.
To test disputes webhooks, you need to wait a few minutes after creating the dispute for the actions to become available. You can then perform the actions to trigger the webhooks.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED and INQUIRY respectively.
You can create an INR case for a transaction and test triggering the webhook.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are MERCHANDISE_OR_SERVICE_NOT_RECEIVED and INQUIRY respectively.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED and CHARGEBACK respectively.
If you have opted out of the dispute stage, you can create an INR case for a transaction and test triggering this webhook in the claim stage.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are MERCHANDISE_OR_SERVICE_NOT_RECEIVED and CHARGEBACK respectively.
You can create an unauthorized case for a transaction and test triggering the webhook.
For 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.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are UNAUTHORISED and CHARGEBACK respectively.
You can test triggering the webhook by creating a dispute for a transaction error using one of these dispute reasons: CREDIT_NOT_PROCESSED, DUPLICATE_TRANSACTION, INCORRECT_AMOUNT, PAYMENT_BY_OTHER_MEANS, CANCELED_RECURRING_BILLING, or OTHER.
For more information about the dispute reasons, see Dispute reasons.
Test steps, Expected outcome
Test steps
Expected outcome
Buyer: Log in to your sandbox personal account and create a case with one of the dispute reasons.
The system triggers the CUSTOMER.DISPUTE.CREATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the parameter values of reason and dispute_life_cycle_stage are the dispute reason that you provided and CHARGEBACK respectively.
You can test that a buyer cannot open a duplicate dispute on a transaction that already has an existing dispute. Even after the original dispute case is closed, the buyer cannot open a new dispute on the same transaction.
You can test this webhook in the claim stage for these scenarios.
If you have opted out of the dispute stage, you can accept a claim for a case and provide the buyer with the return shipping address. Then, test as a buyer by returning the item and providing the return tracking information.
Select Change case type and update the reason to SNAD or unauthorized activity.
The system triggers CUSTOMER.DISPUTE.UPDATED webhook.
After receiving the webhook notification, you can retrieve the dispute details and check if the reason parameter value contains the updated dispute reason.
To simulate Disputes API responses, inject test values as a path or query parameter in the request URL. These methods allow you to trigger specific error responses without creating actual disputes.