Test and go live

Implement and validate the PayPal Disputes API in sandbox and live environments as a developer or QA engineer.

Simulate test scenarios

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.

Prerequisites

Ensure you set up the sandbox environment.
Ensure you set up buyer-side credentials in the sandbox environment. This is required to create disputes or change dispute reasons as a buyer.

Simulate buyer actions

Before testing dispute responses for your integration, you need to simulate buyer actions to create the disputes and transactions in the sandbox environment.

Create transaction

To create a transaction in the sandbox environment, do these steps:

Log in to your sandbox personal account as a buyer.
Select Send and Request and follow the on-page instructions to send money to your sandbox business account’s email ID.
For a transaction to be eligible for chargeback, ensure you use a credit card to send money.
Select Go to Summary.
In the Recent activity section, select the transaction.
On the Summary page, copy the Transaction ID. Use this value to create a dispute.

Create dispute

You can create disputes as a buyer using this endpoint and test how to handle them in the sandbox environment.

This is a sandbox-only endpoint. You cannot use it to create disputes in the live environment.

Use a valid access token, include the PayPal-Auth-Assertion request header with a valid JWT, and make a POST call to the /v1/customer/disputes endpoint. Include the following parameters:

Parameter	Description	Action
`disputed_transactions` array	Array of transaction details for which the dispute is created.	Pass the transaction ID retrieved after creating a transaction in the `buyer_transaction_id` parameter.
`reason` string	Reason for the dispute. For more information, see Dispute reasons.	Pass the reason for which you are disputing the transaction.
`dispute_amount` object	Currency and value of the amount in dispute. The amount value must be less than or equal to the transaction amount of the created transaction.	Pass the currency and amount details.
`extensions` object	Additional dispute details, including whether the merchant was contacted, the contact outcome, and the issue type.	Pass the additional dispute details as needed.

curl -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'Content-Type: multipart/form-data' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-F 'input={
    "disputed_transactions": [{
        "buyer_transaction_id": "BUYER-TRANSACTION-ID"
        }],
    "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
    "dispute_amount": { 
        "currency_code":"USD", 
        "value": "20"
        },
    "extensions": {
        "merchant_contacted": true,
        "merchant_contacted_outcome": "NO_RESPONSE",
        "merchandize_dispute_properties": {
          "issue_type": "PRODUCT"
        }
    }
};type=application/json'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

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.To test Accelerated Response, see Accelerated Response sandbox testing.

Create chargeback

You can create chargebacks using this endpoint and test how to handle them in the sandbox environment.

This is a sandbox-only endpoint. You cannot use it to create chargebacks in the live environment.

Use a valid access token and make a POST call to the /v2/customer-support/process-chargeback endpoint. Include the following parameters:

Parameter	Description	Action
`adjacency` Required, string	Payment method used for the transaction.	Set the value as `PAYPAL` for PayPal transactions.
`file_layout` Required, string	Format or layout for the chargeback event.	Set the value as `ATCK_CB` for PayPal transactions.
`merchant_id` Required, string	Unique identifier for the merchant.	Pass the merchant ID associated with the PayPal account.
`financial_institution.processor` Required, string	Name of the payment processor.	Set the value as `FDMS` for PayPal transactions.
`transaction.id_enc` Required, string	Encrypted transaction identifier of the transaction for which the chargeback is created.	Pass the `SELLER-TRANSACTION-ID` in this parameter. This is the transaction ID available when you log in using the business test account.
`transaction.amount` Required, object	Currency and amount for the transaction.	Pass the currency and amount details.
`instrument` Required, object	Details about the payment instrument used for the transaction.	Pass the payment instrument details.
`instrument.instrument_type` Required, string	Type of payment instrument used for the transaction. Possible values: `CARD`, `BANK`, `CREDIT`, and so on.	Set the value as `CARD` for card-funded transactions.
`dispute` Required, object	Details about the dispute.	Pass the dispute details.
`dispute.receive_date` string	Date and time when the chargeback was received.	Pass a current value for this parameter.
`dispute.money_movement_date` string	Date and time when the money movement happened.	Pass a current value for this parameter.
`dispute.response_date` string	Date and time when the response to the chargeback is due.	Pass a future value for this parameter.

curl -X POST https://api-m.sandbox.paypal.com/v2/customer-support/process-chargeback \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "adjacency": "PAYPAL",
    "file_layout": "ATCK_CB",
    "merchant_id": "99038409233245",
    "financial_institution": {
        "processor": "FDMS"
    },
    "transaction": {
        "id_enc": "SELLER-TRANSACTION-ID",
        "amount": {
            "currency_code": "USD",
            "value": "20"
        }
    },
    "instrument": {
        "instrument_type": "CARD",
        "card_brand": "VISA",
        "credit_card_transaction_id": "2347289342893472",
        "external": false
    },
    "dispute": {
        "id": null,
        "stage": "CHARGEBACK",
        "response_date": "2023-07-16T12:05:22.544Z",
        "status": "2",
        "amount": {
            "currency_code": "USD",
            "value": "10"
        },
        "receive_date": "2025-06-16T12:05:22.544Z",
        "event_code": "CHARGEBACK_INITIATED",
        "money_movement_date": "2025-06-16T12:05:22.544Z",
        "event_type": "DEBIT",
        "chargeback_type": "REPORTED_TO_PROCESSOR",
        "processor_info": {
            "reference_number": "31639435342702423793399",
            "reason_code": "1330",
            "notes": "TEST_MEMO"
        }
    }
}'

{
  "dispute_id": "PP-D-1234"
}

A successful call returns a 201 Created response and a dispute ID. Use the dispute ID to perform subsequent tests on the dispute.

Change dispute reason

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.

Use a valid access token, include the PayPal-Auth-Assertion request header with a valid JWT, and make a POST call to the /v1/customer/disputes/{ID}/change-reason endpoint. Include the following parameters:

Parameter name	Description	Action
`reason` string	New reason for the dispute.	Set the value to the new dispute reason. For more information, see Dispute reasons.
`note` string	Note explaining the reason for the change.	Pass the reason for the change if needed.
`item_info` array	Details about the disputed item if more than one item was available in the disputed transaction.	Pass the item details if needed.

Path parameter: ID is the dispute_id returned in the Create dispute response.

curl -X POST "https://api-m.sandbox.paypal.com/v1/customer/disputes/{ID}/change-reason" \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'Content-Type: multipart/related' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-F 'input={
    "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
    "note": "Product is not as advertised",
    "item_info":
    [
        {
            "item_name": "item 1",
            "item_quantity": "2",
            "reason": "MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED",
            "item_type": "PRODUCT",
            "product_details":
            {
                "sub_reason": "DELAYED",
                "category": "OTHER"
            },
            "expected_refund":
            {
                "currency_code": "USD",
                "value": "10"
            }
        }
    ]
};type=application/json'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

A successful call returns a 200 OK response and an HATEOAS link for the dispute.

Accept offer to resolve 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
`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."
}'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

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.

Deny offer to resolve dispute

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
`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.

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/deny-offer \
  --header 'Authorization: Bearer ACCESS-TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  --data '{
  "note": "Refund offer is low."
}'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

A successful call returns an HTTP 200 OK status code and a HATEOAS link to the dispute.

Simulate PayPal actions

Settle dispute

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
`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.

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/adjudicate \
  --header 'Authorization: Bearer ACCESS-TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "adjudication_outcome": "BUYER_FAVOR"
}'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

A successful call returns an HTTP 200 OK status code and a HATEOAS link to the dispute.

Update dispute status

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
`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.

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/customer/disputes/{id}/require-evidence \
  --header 'Authorization: Bearer ACCESS-TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "BUYER_EVIDENCE"
}'

{
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-D-27803",
      "rel": "self",
      "method": "GET"
    }
  ]
}

A successful call returns an HTTP 200 OK status code and a HATEOAS link to the dispute.

Test dispute scenarios

You can use the scenarios in this section to test how your integration handles disputes and chargebacks in the sandbox environment.

Test internal disputes

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
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.	Buyer: Create a dispute using the PayPal wallet. Merchant: Provide the requested evidence.	The merchant receives the relevant notifications. The merchant’s account balance remains unchanged.
Dispute WITH HOLD, MERCHANT WINS CASE	The buyer creates a dispute for a transaction where PayPal holds the money in the merchant’s account. The merchant provides evidence and the case resolves in the merchant’s favor. PayPal releases the hold.	Buyer: Create a dispute using the PayPal wallet. Merchant: Provide the requested evidence.	The merchant receives the relevant notifications. PayPal releases the hold on the merchant’s account.
Dispute NO HOLD, MERCHANT LOSES CASE (no data), NO SELLER PROTECTION, DISPUTE FEE is charged	The buyer creates a dispute for a transaction where PayPal does not hold the money in the merchant’s account. The merchant does not provide evidence and the case resolves in the buyer’s favor.	Buyer: Create a dispute using the PayPal wallet. Merchant: Do not provide evidence.	The merchant receives the relevant notifications. The case resolves in the buyer’s favor. The transaction is not eligible for Seller Protection. PayPal debits the merchant’s account.

Possible notifications

Webhooks:
- Case creation: CUSTOMER.DISPUTE.CREATED
- Merchant response for evidence submission: CUSTOMER.DISPUTE.UPDATED
- Case resolution: CUSTOMER.DISPUTE.RESOLVED
Emails: Case creation, response request, and resolution.

Test chargebacks

You can create chargebacks for card transactions and test them using these scenarios.Test data conditions:

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.

Scenario	Description	Test steps	Expected outcome
Chargeback WITH PROVISIONAL CREDIT, MERCHANT WINS CASE	A chargeback is created for a transaction. The merchant provides evidence, the case resolves in the merchant’s favor, and the merchant retains the provisional credit.	Buyer: Create a chargeback. Merchant: Provide the requested evidence.	The merchant receives the relevant notifications. The merchant’s account balance remains unchanged.
Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT WINS CASE	A chargeback is created 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.	Buyer: Create a chargeback. Merchant: Provide the requested evidence.	The merchant receives the relevant notifications. The merchant’s account balance remains unchanged.
Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data)	A chargeback is created for a transaction where PayPal does not hold the money in the merchant’s account. The merchant does not provide evidence, the case resolves in the buyer’s favor, and the merchant loses the provisional credit.	Buyer: Create a chargeback. Merchant: Do not provide evidence.	The merchant receives the relevant notifications. The case resolves in the buyer’s favor. PayPal debits the merchant’s account.
Chargeback WITHOUT PROVISIONAL CREDIT, MERCHANT LOSES CASE (no data)	A chargeback is created for a transaction where PayPal does not hold the money in the merchant’s account. The merchant does not provide evidence and the case resolves in the buyer’s favor.	Buyer: Create a chargeback. Merchant: Do not provide evidence.	The merchant receives the relevant notifications. The case resolves in the buyer’s favor. PayPal debits the merchant’s account.
Chargeback WITH PROVISIONAL CREDIT, MERCHANT LOSES CASE (adjudication)	A chargeback is created 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 buyer’s favor and the merchant loses the provisional credit.	Buyer: Create a chargeback. Merchant: Provide the requested evidence.	The merchant receives the relevant notifications. The case adjudicates in the buyer’s favor after evidence review. PayPal debits the merchant’s account.

Possible notifications

Webhooks:
- Case creation: CUSTOMER.DISPUTE.CREATED
- Merchant response for evidence submission: CUSTOMER.DISPUTE.UPDATED
- Case resolution: CUSTOMER.DISPUTE.RESOLVED
Emails: Case creation, response request, and resolution.

Test merchant response

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. Key terms:

INR: Item Not Received
SNAD: Significantly Not As Described

Check response due date and HATEOAS links

You can use the Show dispute details response to determine how and when to respond to disputes.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Retrieve the dispute details.	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.

Inquiry stage

You can use the procedures in this section to test dispute response handling during the inquiry stage.

Send message to other party

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. Check if the send message action is available in the HATEOAS links. Send a message to the other party.	The API returns a `200 OK` response. You can retrieve the dispute details and check the `messages` array in the response.

Make offer to resolve dispute

You can test making an offer to the buyer in these scenarios.

Note: Merchant must have sufficient funds to issue a refund.

REFUND_WITH_RETURN - SNAD case

For a SNAD case in the inquiry stage, you can test offering the buyer a refund in exchange for returning the item.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the following parameters: `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.

REFUND_WITH_REPLACEMENT - SNAD case

For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item along with a refund.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the following parameters: `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.

REPLACEMENT_WITHOUT_REFUND - SNAD case

For a SNAD case in the inquiry stage, you can test offering the buyer a replacement item without a refund.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the `offer_type` parameter value as `REPLACEMENT_WITHOUT_REFUND`.	The API returns a `200 OK` response. You can retrieve the dispute details and check the `offer.offer_type` parameter in the response.

REFUND

For an INR or SNAD case in the inquiry stage, you can test offering the buyer a refund without the replacement of the item.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the following parameters: `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.

Acknowledge returned item

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the following parameters: `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. Buyer: In the PayPal Resolution Center, view the dispute details and accept the offer. Add the tracking information for the returned item. Merchant: Retrieve the dispute details. Check if the acknowledge returned item action is available in HATEOAS links. Acknowledge the returned item.	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.

Provide evidence

You can test providing evidence for these evidence types. This section applies to INR cases only.

PROOF_OF_FULFILLMENT

You can test the PROOF_OF_FULFILLMENT evidence type by providing tracking information for the INR cases.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `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.

PROOF_OF_REFUND

You can test the PROOF_OF_REFUND evidence type by providing refund details for the INR cases.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `evidence_type`: Set the value as `PROOF_OF_REFUND`. `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.

OTHER

You can test the OTHER evidence type by providing notes or documents (including photos and files) for the INR cases.

For more information about the supported file types and size limits, see Supported file types and sizes.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `evidence_type`: Set the value as `OTHER`. `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.

Accept claim

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. 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.

Escalate dispute to claim

You can test escalating the dispute to a claim to simulate cases where you cannot reach an amicable resolution with the buyer.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. Check if the escalate action is available in the HATEOAS links. Escalate the dispute to claim.	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.

To test Accelerated Response, see Accelerated Response sandbox testing.

Claim stage

You can use the procedures in this section to test dispute response handling during the claim stage.

Provide evidence

You can test providing evidence for these evidence types.

PROOF_OF_FULFILLMENT - INR case

You can test the PROOF_OF_FULFILLMENT evidence type by providing tracking information for the INR cases.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `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.

PROOF_OF_REFUND

You can test the PROOF_OF_REFUND evidence type by providing refund details for the INR or SNAD cases.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `evidence_type`: Set the value as `PROOF_OF_REFUND`. `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.

OTHER

You can test the OTHER evidence type by providing notes or documents (including photos and files) for the INR or SNAD cases.

For more information about the supported file types and size limits, see Supported file types and sizes.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Retrieve the dispute details. 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`. Provide the evidence with the following parameters within the `evidences` object: `evidence_type`: Set the value as `OTHER`. `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.

Accept claim

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.

REFUND

The test procedure to refund the dispute amount is identical in the inquiry and claim stages. For detailed information, see Accept claim.

REFUND_WITH_RETURN

You can test accepting the claim for a SNAD case and refunding the buyer after they return the item to a specified address.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD dispute. Merchant: Retrieve the dispute details. Check if the accept claim action is available in the HATEOAS links. Accept the claim with the following parameters: `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.

PARTIAL_REFUND

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD dispute. Merchant: Retrieve the dispute details. Check if the accept claim action is available in the HATEOAS links. Accept the claim with the following parameters: `refund_amount`: Amount to refund. `accept_claim_type`: Set the value as `PARTIAL_REFUND`.	The API returns a `200 OK` response. You can retrieve the dispute details and track the updates. 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.

Acknowledge returned item

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case. Merchant: Retrieve the dispute details. Check if the make offer action is available in the HATEOAS links. Make an offer with the following parameters: `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. Buyer: In the PayPal Resolution Center, view the dispute details and accept the offer. Add the tracking information for the returned item. Merchant: Retrieve the dispute details. Check if the acknowledge returned item action is available in HATEOAS links. Acknowledge the returned item.	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.

Appeal dispute

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, testallowappeal@personal.example.com). 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, testnoappeal@personal.example.com). You can appeal the case and provide evidence using these evidence types.

PROOF_OF_FULFILLMENT

If the case is resolved in the buyer’s favor, you can appeal by providing the fulfillment information for INR, unauthorized, or other cases.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case. Merchant: Settle the dispute with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer’s favor. Retrieve the dispute details. Check if the appeal action is available in the HATEOAS links. Appeal the case with the following parameters within the `evidences` object: `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: If the `evidences` object contains the `evidence_type` and `evidence_info.tracking_info` parameter values you provided. If the `status` and `dispute_life_cycle_stage` parameter values are `UNDER_REVIEW` and `PRE_ARBITRATION` respectively.

PROOF_OF_REFUND

If the case is resolved in the buyer’s favor, you can appeal by providing the refund information for all the dispute reasons.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Settle the dispute with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer’s favor. Retrieve the dispute details. Check if the appeal action is available in the HATEOAS links. Appeal the case with the following parameters within the `evidences` object: `evidence_type`: Set the value as `PROOF_OF_REFUND`. `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: 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.

OTHER

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Settle the dispute with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer’s favor. Retrieve the dispute details. Check if the appeal action is available in the HATEOAS links and the `evidences` object for the requested evidence. Appeal the case with the following parameters within the `evidences` object: `evidence_type`: Set the value as `OTHER`. `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 `evidences` object in the response.

Accelerated Response sandbox testing

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.

curl -X POST https://api-m.sandbox.paypal.com/v1/customer/disputes \
-H 'Authorization: Bearer A21AAItEDV4r4hH1p72Aw8iciCdCyVmIeiXi7XkX8I38AHTDN7Zc4KywkWgsjH8gP4hfQwWFVn8Hj880z_s2ormzjPh80D_5w' \
-H 'Content-Type: multipart/form-data' \
-H 'PayPal-Auth-Assertion: eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJpc3MiOiJBWmdidVpPU1B0YnJIWnNrNFZHeFAxOVFvZFUzVk91R1R5UEhhRTZJNkJVVm9NdTJvSnpIZExGeVc3Rmpvd1labGdVaEk4eWRzcXh6RlAtSSIsImVtYWlsIjoic2ItcmstYnV5ZXJAcGVyc29uYWwuZXhhbXBsZS5jb20ifQ.' \
-F 'input={
    "disputed_transactions": [{
        "buyer_transaction_id": "2NJ45340EV624100G"
        }],
    "reason": "MERCHANDISE_OR_SERVICE_NOT_RECEIVED",
    "dispute_amount": {
        "currency_code":"USD",
        "value": "5"
        },
    "extensions": {
        "merchant_contacted": true,
        "merchant_contacted_outcome": "NO_RESPONSE",
        "merchandize_dispute_properties": {
          "issue_type": "PRODUCT"
        }
    },
    "evidences": [{
            "notes": "ACCELERATED_RESPONSE_ENABLED"
        }
    ]
};type=application/json'

{
  "links": [{
    "href": "https://api-m.sandbox.paypal.com/v1/customer/disputes/PP-R-TOW-10161582",
    "rel": "self",
    "method": "GET"
  }]
}

Escalation simulation

To simulate the day of escalation in the sandbox environment, use the following transaction amounts:

Transaction amount (USD)	Simulated escalation day
5.00 – 5.99	Day 5 escalation
9.00 – 9.99	Day 9 escalation
≥ 11.00	Day 11 escalation

Create a transaction with one of the listed amounts, then use that transaction when creating the dispute to simulate the corresponding escalation day.

Applicable dispute reasons

Accelerated Response currently applies to these dispute reasons:

MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED
MERCHANDISE_OR_SERVICE_NOT_RECEIVED

Once the dispute is created, you can perform any of the actions listed under the Inquiry stage section.

Applicable document proofs

Refer to the applicable documentation requirements in Supported file types and sizes.

Test webhooks

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.

Test dispute created webhook

You can test the CUSTOMER.DISPUTE.CREATED webhook in both the inquiry and claim stages.

Inquiry stage

You can test this webhook in the inquiry stage for these scenarios.

SNAD case

You can create a SNAD case for a transaction and test triggering the webhook.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case.	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.

INR case

You can create an INR case for a transaction and test triggering the webhook.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case.	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.

Claim stage

You can test this webhook in the claim stage for these scenarios.

SNAD case

If you have opted out of the dispute stage, you can create a SNAD case for a transaction and test triggering this webhook in the claim stage.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD case.	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.

INR case

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR case.	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.

Unauthorized case

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an unauthorized case.	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.

Transaction error case

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
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.

Duplicate dispute creation (negative testing)

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Merchant: Settle the dispute with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer’s favor. Buyer: Check if you can create a dispute for the same transaction.	You cannot open a duplicate dispute on the same transaction.

Test dispute updated webhook

You can test the CUSTOMER.DISPUTE.UPDATED webhook in both the inquiry and claim stages.

Inquiry stage

You can test this webhook in the inquiry stage for this scenario.

Buyer sends message to merchant

You can test this webhook by sending a message to the merchant as a buyer for the INR or SNAD case.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR or SNAD case. Select the case ID and send a message to the merchant.	The system triggers `CUSTOMER.DISPUTE.UPDATED` webhook. After receiving the webhook notification, you can retrieve the dispute details and check if the message details are available in the `messages` array.

Claim stage

You can test this webhook in the claim stage for these scenarios.

Buyer provides return tracking information

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.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a SNAD dispute. Merchant: Accept the claim. Buyer: Provide the tracking number through the PayPal Resolution Center.	The system triggers `CUSTOMER.DISPUTE.UPDATED` webhook. After receiving the webhook notification, you can retrieve the dispute details and check the response parameters to get the tracking information.

Buyer changes reason

You can test changing the dispute reason of the INR dispute to SNAD or unauthorized activity.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create an INR dispute. 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.

Test dispute resolved webhook

You can test the CUSTOMER.DISPUTE.RESOLVED webhook for these scenarios.

Buyer cancels dispute

You can test cancelling the dispute in the Resolution Center as a buyer to trigger the webhook.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a dispute. Select the case ID and then, select Cancel case.	The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook.

Settle dispute (buyer wins)

You can test settling the case in the buyer’s favor to trigger the webhook.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a dispute. Merchant: Settle the dispute with `adjudication_outcome` as `BUYER_FAVOR` to resolve the case in the buyer’s favor.	The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook.

Settle dispute (merchant wins)

You can test settling the case in the merchant’s favor to trigger the webhook.

Test steps	Expected outcome
Buyer: Log in to your sandbox personal account and create a dispute. Merchant: Settle the dispute with `adjudication_outcome` as `SELLER_FAVOR` to resolve the case in the merchant’s favor.	The system triggers `CUSTOMER.DISPUTE.RESOLVED` webhook.

Identify unique webhook through webhook ID

You can test identifying a specific webhook using the webhook ID in the webhook payload.

Test steps	Expected outcome
Merchant: Subscribe and listen to the dispute webhooks: `CUSTOMER.DISPUTE.CREATED`, `CUSTOMER.DISPUTE.RESOLVED`, `CUSTOMER.DISPUTE.UPDATED`. Buyer: Log in to your sandbox personal account and create a dispute.	The system triggers the `CUSTOMER.DISPUTE.CREATED` webhook notification. You can use the unique webhook ID in the payload to identify the webhook.

Test API calls: use test values and simulate responses

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.

Sample - test value as path parameter
Sample - test value as query parameter

Path parameter	Simulated error response
`/v1/customer/disputes/ERRDIS015`	`FORBIDDEN`

curl -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes/ERRDIS015 \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json'

{
    "name": "FORBIDDEN",
    "message": "No permission for the requested operation",
    "debug_id": "e90ec082e0e4d"
}

Query parameter	Simulated error response
`/v1/customer/disputes?disputed_transaction_id=ERRDIS023`	`FORBIDDEN`

curl -X GET https://api-m.sandbox.paypal.com/v1/customer/disputes?disputed_transaction_id=ERRDIS023 \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: application/json'

{
    "name": "FORBIDDEN",
    "message": "No permission for the requested operation",
    "debug_id": "e90ec082e0e4d"
}

Common issues

If an API call fails while you test , check for these common issues:

400 Bad Request when required fields or formats are invalid.
401 Unauthorized when the access token is missing, expired, or invalid.
403 Forbidden when the app is not permitted to perform this action.

For more details, see the HTTP status codes and error messages.

Go live

Set up live account.
Set up webhooks to get real-time notifications about dispute events, such as created, updated, or resolved disputes.
Go live with your app.

Grow your business

Send payouts

Manage disputes

Analyze reports

Agentic commerce

Simulate test scenarios

Prerequisites

Simulate buyer actions

Simulate PayPal actions

Test dispute scenarios

Test merchant response

Check response due date and HATEOAS links

Inquiry stage

Claim stage

Appeal dispute

Accelerated Response sandbox testing

Escalation simulation

Applicable dispute reasons

Applicable document proofs

Test webhooks

Test dispute created webhook

Inquiry stage

Claim stage

Test dispute updated webhook

Inquiry stage

Claim stage

Test dispute resolved webhook

Identify unique webhook through webhook ID

Test API calls: use test values and simulate responses

Common issues

Go live

​Simulate test scenarios

​Prerequisites

​Simulate buyer actions

​Simulate PayPal actions

​Test dispute scenarios

​Test merchant response

​Check response due date and HATEOAS links

​Inquiry stage

​Claim stage

​Appeal dispute

​Accelerated Response sandbox testing

​Escalation simulation

​Applicable dispute reasons

​Applicable document proofs

​Test webhooks

​Test dispute created webhook

​Inquiry stage

​Claim stage

​Test dispute updated webhook

​Inquiry stage

​Claim stage

​Test dispute resolved webhook

​Identify unique webhook through webhook ID

​Test API calls: use test values and simulate responses

​Common issues

​Go live

Simulate test scenarios

Prerequisites

Simulate buyer actions

Simulate PayPal actions

Test dispute scenarios

Test merchant response

Check response due date and HATEOAS links

Inquiry stage

Claim stage

Appeal dispute

Accelerated Response sandbox testing

Escalation simulation

Applicable dispute reasons

Applicable document proofs

Test webhooks

Test dispute created webhook

Inquiry stage

Claim stage

Test dispute updated webhook

Inquiry stage

Claim stage

Test dispute resolved webhook

Identify unique webhook through webhook ID

Test API calls: use test values and simulate responses

Common issues

Go live