Subscribe to disputes webhooks

DocsCurrent

Last updated: Nov 18th, 7:50am

Merchants can subscribe to disputes webhooks.

Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook at PayPal, users configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. PayPal signs each notification message that it delivers to your webhook listener.

For more information about how to integrate with webhooks, see the webhooks integration guide.

Notification flow

If a merchant subscribes to dispute webhooks, the following notification flow occurs:

  1. When a customer files a case, the merchant is notified with a CUSTOMER.DISPUTE.CREATED webhook that includes the dispute ID.
  2. The merchant can use the dispute ID to show dispute details and take appropriate action based on the allowable actions in the HATEOAS links that appear in the response.
  3. The merchant can either:
    • Provide sufficient evidence and dispute the case.
    • Accept the claim, which refunds the disputed amount.

Events

A merchant who subscribes to dispute webhooks receives these webhook events notifications:

Event Triggered when
CUSTOMER.DISPUTE.CREATED A dispute is created.
CUSTOMER.DISPUTE.RESOLVED A dispute is resolved.
CUSTOMER.DISPUTE.UPDATED A dispute is updated.

For more information about Disputes API webhooks, see the Disputes webhook event names.

Webhook details

A webhook for a disputes event includes these details:

  • dispute_id. The ID of the dispute.
  • create_time. The date and time when the dispute was created, in Internet date and time format.
  • update_time. The date and time when the dispute was last updated, in Internet date and time format.
  • disputed_transactions. An array of transactions for which the disputes were created:

    • buyer_transaction_id. The ID, as seen by the customer, for this transaction.
    • seller_transaction_id. The ID, as seen by the merchant, for this transaction.
    • create_time. The date and time when the transaction was created, in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
      • date_time. The date and time, in Internet date and time format. Seconds are required, while fractional seconds are optional.
    • transaction_status. The transaction status:
      • COMPLETED. The transaction processing is completed.
      • UNCLAIMED. The items in the transaction are unclaimed. If they are not claimed within 30 days, the funds are returned to the sender.
      • DENIED. The transaction was denied.
      • FAILED. The transaction failed.
      • HELD. The transaction is on hold.
      • PENDING. The transaction is waiting to be processed.
      • PARTIALLY_REFUNDED. The payment for the transaction was partially refunded.
      • REFUNDED. The payment for the transaction was successfully refunded.
      • REVERSED. The payment for the transaction was reversed due to a chargeback or other reversal type.
      • CANCELLED. The transaction is cancelled.
    • invoice_number. The ID of the invoice that is associated with the payment.
    • seller. The details for the merchant who receives the funds and fulfills the order. For example, merchant ID, contact email address, and so on.
      • name. The name of the merchant.
      • merchant_id. The PayPal account ID for the merchant.
    • custom. A free-text field that is entered by the merchant during checkout.
    • items. An array of items that were purchased as part of the transaction:
      • item_id. The ID of the item.
      • item_name. The item name.
      • item_description. The item description.
      • item_quantity. The count of the item in the dispute.
      • item_type. The type of the item which has the issue.
      • reason. The reason for the item-level dispute:
        • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
        • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service was not as described.
        • UNAUTHORISED. The customer did not authorize the purchase of the merchandise or service.
        • CREDIT_NOT_PROCESSED. The refund or credit wasn't processed for the customer.
        • DUPLICATE_TRANSACTION. The transaction was a duplicate.
        • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
        • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
        • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
        • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
        • OTHER. Other.
      • dispute_amount. The amount in the transaction that the customer originally disputed. Because customers can sometimes dispute only part of the payment, the disputed amount might be different from the total gross or net amount of the original transaction.
        • currency_code. The three-character ISO-4217 currency code that identifies the currency.
        • value. The value, which might be:
          • An integer for currencies like JPYthat are not typically fractional.
          • A decimal fraction for currencies like TND that are subdivided into thousandths.

          For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

      • notes. Any notes provided with the item.
      • partner_transaction_id. The ID of the transaction in the partner system. The partner transaction ID is returned at an item level because the partner might show different transactions for different items in the cart.

  • reason. The reason for the item-level dispute:

    • MERCHANDISE_OR_SERVICE_NOT_RECEIVED. The customer did not receive the merchandise or service.
    • MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED. The customer reports that the merchandise or service is not as described.
    • UNAUTHORISED. The customer did not authorize the purchase of the merchandise or service.
    • CREDIT_NOT_PROCESSED. The refund or credit was not processed for the customer.
    • DUPLICATE_TRANSACTION. The transaction was a duplicate.
    • INCORRECT_AMOUNT. The customer was charged an incorrect amount.
    • PAYMENT_BY_OTHER_MEANS. The customer paid for the transaction through other means.
    • CANCELED_RECURRING_BILLING. The customer was being charged for a subscription or a recurring transaction that was canceled.
    • PROBLEM_WITH_REMITTANCE. A problem occurred with the remittance.
    • OTHER. Other.

    For information about the required information for each dispute reason and associated evidence type, see dispute reasons.

  • status. The status of the dispute:

    • OPEN. Open.
    • WAITING_FOR_BUYER_RESPONSE. The dispute is waiting for a response from the customer.
    • WAITING_FOR_SELLER_RESPONSE. The dispute is waiting for a response from the merchant.
    • UNDER_REVIEW. The dispute is under review.
    • RESOLVED. The dispute is resolved.
    • OTHER. Another reason.
  • dispute_amount. The amount in the transaction that the customer originally disputed. Because customers can sometimes dispute only part of the payment, the disputed amount might be different from the total gross or net amount of the original transaction.

    • currency_code. The three-character ISO-4217 currency code that identifies the currency.
    • value. The value, which might be:
      • An integer for currencies like JPY that are not typically fractional.
      • A decimal fraction for currencies like TND that are subdivided into thousandths.

      For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

  • dispute_asset. The asset in the transaction that the customer disputed. This will usually be present for disputes related to crypto transactions.

    • asset_symbol. The Cryptocurrency ticker symbol/code as assigned by liquidity providers (exchanges).
      • BTC. The ticker symbol for Bitcoin.
      • ETH. The ticker symbol for Ethereum.
      • BCH. The ticker symbol for Bitcoin Cash.
      • LTC. The ticker symbol for Litecoin.
    • quantity. Quantity of a cryptocurrency asset. This is a decimal number with a scale defined for each Cryptocurrency by the founders. For example
      • Bitcoin(BTC) has 8 as scale,
      • Ethereum (ETH) has 18 as scale.

        PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ethereum.

  • dispute_outcome. The outcome of a dispute.

    • outcome_code. The outcome of a resolved dispute. The possible values are:
      • RESOLVED_BUYER_FAVOUR. The dispute was resolved in the customer's favor.
      • RESOLVED_SELLER_FAVOUR. The dispute was resolved in the merchant's favor.
      • RESOLVED_WITH_PAYOUT. PayPal provided the merchant or customer with protection and the case is resolved.
      • CANCELED_BY_BUYER. The customer canceled the dispute.
      • ACCEPTED. PayPal accepted the dispute.
      • DENIED. PayPal denied the dispute.
      • NONE. Cases resolved without an outcome due to subsequent case on the same transaction.
    • outcome_reason. The reason for the outcome of a resolved dispute. For a list of possible values, see adjudication reasons.
    • amount_refunded. The amount that either the merchant or PayPal refunds the customer.
      • currency_code. The three-character ISO-4217 currency code that identifies the currency.
      • value. The value, which might be:
        • An integer for currencies like JPY that are not typically fractional.
        • A decimal fraction for currencies like TND that are subdivided into thousandths.

        For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    • asset_refunded. The asset that either the merchant or PayPal refunds the customer.
      • asset_symbol. The Cryptocurrency ticker symbol/code as assigned by liquidity providers (exchanges).
        • BTC. The ticker symbol for Bitcoin.
        • ETH. The ticker symbol for Ethereum.
        • BCH. The ticker symbol for Bitcoin Cash.
        • LTC. The ticker symbol for Litecoin.
      • quantity. Quantity of a cryptocurrency asset. This is a decimal number with a scale defined for each Cryptocurrency by the founders. For example
        • Bitcoin(BTC) has 8 as scale,
        • Ethereum (ETH) has 18 as scale.

        PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ethereum.

  • dispute_life_cycle_stage. The stage in the dispute lifecycle.

    The possible values are:

    • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:
      • Has not received goods or a service.
      • Reports that the received goods or services are not as described.
      • Needs more details, such as a copy of the transaction or a receipt.
    • CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:
      • Accept the claim.
      • Submit evidence to challenge the claim.
      • Make an offer to the customer to resolve the claim.
    • PRE_ARBITRATION. The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.
    • ARBITRATION. The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.
  • dispute_channel. The channel where the customer created the dispute.

    The possible values are:

    • INTERNAL. The customer contacts PayPal to file a dispute with the merchant.
    • EXTERNAL. The customer contacts their card issuer or bank to request a refund.
  • messages. An array of messages posted by the customer and merchant.

    • posted_by. The customer or merchant who posted the message. The possible values are:
      • BUYER. The customer posted the message.
      • SELLER. The merchant posted the message.
    • time_posted. The date and time when the message was posted, in Internet date and time format.
    • content. The customer- or merchant-posted content.
    • documents. An array of metadata containing metadata information about the documents uploaded as part of the message posted.
      • name. The document name.
      • url. The downloadable URL for the document for which the client has access.
  • external_reason_code. The code that identifies the reason for the credit card chargeback. Each card issuer follows their own standards for defining reason type, code, and its format. For more details about the external reason code, see the card issuers site. Available for only unbranded transactions when dispute_channel is EXTERNAL.
  • adjudications. The Teammate Adjudication details for the dispute.

    • type. The type of adjudication. The possible values are:
      • DENY_BUYER. The decision is to deny the buyer for the dispute.
      • PAYOUT_TO_BUYER. The decision is to payout to the buyer.
      • PAYOUT_TO_SELLER. The decision is to payout to the seller if the seller was debited earlier.
      • RECOVER_FROM_SELLER. The decision is to charge the seller for the dispute if the seller was not debited already.
    • adjudication_time. The date and time when the adjudication was done, in Internet date and time format.
    • reason. The reason for the adjudication type. See reason for a list of all possible values.
    • dispute_life_cycle_stage. The dispute life cycle stage during the adjudication. The possible values are:
      • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal. Occurs when the customer:
        • Has not received goods or a service.
        • Reports that the received goods or services are not as described.
        • Needs more details, such as a copy of the transaction or a receipt.
      • CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination. Occurs only when the dispute channel is INTERNAL. This stage is a PayPal dispute lifecycle stage and not a credit card or debit card chargeback. All notes that the customer sends in this stage are visible to PayPal agents only. The customer must wait for PayPal’s response before the customer can take further action. In this stage, PayPal shares dispute details with the merchant, who can complete one of these actions:
        • Accept the claim.
        • Submit evidence to challenge the claim.
        • Make an offer to the customer to resolve the claim.
      • PRE_ARBITRATION. The first appeal stage for merchants. A merchant can appeal a chargeback if PayPal's decision is not in the merchant's favor. If the merchant does not appeal within the appeal period, PayPal considers the case resolved.
      • ARBITRATION. The second appeal stage for merchants. A merchant can appeal a dispute for a second time if the first appeal was denied. If the merchant does not appeal within the appeal period, the case returns to a resolved status in pre-arbitration stage.
  • money_movements. The Money movement details for the dispute.

    • affected_party. The affected party in the money movement.
      • SELLER. The money movement is related to the seller.
      • BUYER. The money movement is related to the buyer.
    • type. The type of the money movement.
      • DEBIT. The money movement is a debit transaction.
      • CREDIT. The money movement is a credit transaction.
    • amount. The amount transferred as part of the money movement.
      • currency_code. The three-character ISO-4217 currency code that identifies the currency.
      • value. The value, which might be:
        • An integer for currencies like JPY that are not typically fractional.
        • A decimal fraction for currencies like TND that are subdivided into thousandths.

        For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    • asset. The asset transferred as part of the money movement.
      • asset_symbol. The Cryptocurrency ticker symbol/code as assigned by liquidity providers (exchanges).
        • BTC. The ticker symbol for Bitcoin.
        • ETH. The ticker symbol for Ethereum.
        • BCH. The ticker symbol for Bitcoin Cash.
        • LTC. The ticker symbol for Litecoin.
      • quantity. Quantity of a cryptocurrency asset. This is a decimal number with a scale defined for each Cryptocurrency by the founders. For example
        • Bitcoin(BTC) has 8 as scale,
        • Ethereum (ETH) has 18 as scale.

        PayPal Cryptocurrency platform handles the scale to 8 digits for Bitcoin and its forks or offshoots and Ethereum.

    • initiated_time. The date and time when the money movement was initiated, in Internet date and time format.
    • reason. The reason for the money movement.
      • DISPUTE_SETTLEMENT_FEE. The fee is for dispute settlement.
      • DISPUTE_SETTLEMENT. The money movement is for dispute settlement.
      • DISPUTE_FEE. The money movement is for dispute fee which PayPal charges to sellers for facilitating the online dispute resolution process for transactions that are processed either through a buyer’s PayPal account or through a PayPal guest checkout.
      • CHARGEBACK_FEE. The money movement is for chargeback fee which PayPal charges to sellers for facilitating the chargeback process for transactions that are not processed either through a buyer’s PayPal account or through a guest checkout, and where the buyer pursues a chargeback for the transaction with their card issuer.
  • evidences. An array of evidence documents.

    • evidence_type. The evidence type. For possible values, see evidence_type.
    • evidence_info. The evidence-related information.
    • documents. An array of evidence documents.
    • notes. Any evidence-related notes.
    • source. The source of the evidence.
    • date. The date and time in Internet date and time format. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
    • dispute_life_cycle_stage. The dispute life cycle stage for the evidence. The possible values are:
      • INQUIRY. A customer and merchant interact in an attempt to resolve a dispute without escalation to PayPal.
      • CHARGEBACK. A customer or merchant escalates an inquiry to a claim, which authorizes PayPal to investigate the case and make a determination.
      • PRE_ARBITRATION. The first appeal stage for merchants.
      • ARBITRATION. The second appeal stage for merchants.
    • action_info. The action details for the information. Includes additional information such as the action for which the evidence was requested/submitted and whether the evidence is mandatory for the corresponding action.
  • buyer_response_due_date. The date and time by which the customer must respond to the dispute, in Internet date and time format. If the customer does not respond by this date and time, the dispute is closed in the merchant's favor. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • seller_response_due_date. The date and time by which the merchant must respond to the dispute, in Internet date and time format. If the merchant does not respond by this date and time, the dispute is closed in the customer's favor. For example, yyyy-MM-ddTHH:mm:ss.SSSZ.
  • offer. The merchant-proposed offer for a dispute.

    • buyer_requested_amount. The customer-requested refund for this dispute.
      • currency_code. The three-character ISO-4217 currency code that identifies the currency.
      • value. The value, which might be:
        • An integer for currencies like JPY that are not typically fractional.
        • A decimal fraction for currencies like TND that are subdivided into thousandths.

        For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    • seller_offered_amount. The merchant-offered refund for this dispute.
      • currency_code. The three-character ISO-4217 currency code that identifies the currency.
      • value. The value, which might be:
        • An integer for currencies like JPY that are not typically fractional.
        • A decimal fraction for currencies like TND that are subdivided into thousandths.

        For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

  • refund_details. The refund details.

    • allowed_refund_amount. The maximum refundable amount for the dispute.
      • currency_code. The three-character ISO-4217 currency code that identifies the currency.
      • value. The value, which might be:
        • An integer for currencies like JPY that are not typically fractional.
        • A decimal fraction for currencies like TND that are subdivided into thousandths.

        For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

  • allowed_response_options. The allowed response options for the case update actions.

    • acknowledge_return_item. The allowed response options when the seller acknowledges that the buyer has returned an item for the dispute.
      • ITEM_RECEIVED. The merchant has received the item returned by the customer.
      • ITEM_NOT_RECEIVED. The merchant has not received the item
      • DAMAGED. The items returned by the customer were damaged.
      • EMPTY_PACKAGE_OR_DIFFERENT. The package was empty or the goods were different from what was expected.
      • MISSING_ITEMS. The package did not have all the items that were expected.
    • accept_claim. The allowed response options when the merchant is accepting the claim.
      • accept_claim_typesThe types of refund the merchant can provide the customer.
        • REFUND. The merchant must refund the customer without any item replacement or return. This type is applicable when a merchant is willing to refund the entire dispute amount without any further action from customer. Omit the refund_amount and return_shipping_address parameters from the accept claim call.
        • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item. Include the return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
        • PARTIAL_REFUND. The merchant proposes a partial refund for the dispute.This type is applicable when a merchant is willing to refund an amount lesser than dispute amount. Include the refund_amount parameter as part of the accept claim.
        • REFUND_WITH_RETURN_SHIPMENT_LABEL. The customer must return the item to the merchant and then merchant will refund the money. This type is applicable when a merchant is willing to refund the dispute amount and requires the customer to return the item using the shipment label provided by the merchant. Include the return_shipment_info and return_shipping_address parameter in but omit the refund_amount parameter from the accept claim call.
    • make_offer. The allowed response options when the merchant makes offer to the customer.
      • offer_type. The types of offer the merchant can offer the customer.
        • REFUND. The merchant must refund the customer without any item replacement or return. This offer type is valid in the inquiry phase and occurs when a merchant is willing to refund a specific amount. Buyer acceptance is needed for partial refund offers and dispute is auto closed for full refunds. Include the offer_amount but omit the return_shipping_address parameters from the make offer request.
        • REFUND_WITH_RETURN. The customer must return the item to the merchant and then merchant will refund the money. This offer type is valid in the inquiry phase and occurs when a merchant is willing to refund a specific amount and requires the customer to return the item. Include the return_shipping_address parameter and the offer_amount parameter in the make offer request.
        • REFUND_WITH_REPLACEMENT. The merchant must do a refund and then send a replacement item to the customer. This offer type is valid in the inquiry phase when a merchant is willing to refund a specific amount and send the replacement item. Include the offer_amount parameter in the make offer request.
        • REPLACEMENT_WITHOUT_REFUND. The merchant must send a replacement item to the customer with no additional refunds. This offer type is valid in the inquiry phase when a merchant is willing to replace the item without any refund. Omit the offer_amount parameter from the make offer request.
  • links. An array of request-related HATEOAS links:

    • href. The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
    • rel. The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
    • method. The HTTP method required to make the related call.
ReferencePayPal.comPrivacyCookiesSupportLegalContact

We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies