On this page
No Headings
Last updated: June 16, 2026
PayPal's Chargeback Protection Tool provides security against fraudulent transactions by defending eligible disputes. The tool requires specific integration requirements and mandatory fields to effectively identify and mitigate fraud risk.
Integrate with either JavaScript SDK or Orders v2 API integrations to create and capture orders.
The Chargeback Protection Tool requires a set of mandatory fields.
The following table shows the Orders v2 API parameters to pass to reduce fraudulent transactions using the Chargeback Protection Tool.
Pass the following fields when you send a Capture order request.
| Field name | Description | Type | Notes | Priority |
payer.name | The name of the payer. Supports only the given_name and surname properties. See the parameter defintion for more information. | object | Recommended | |
purchase_units.shipping.address | The address of the person receiving the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. See the parameter definition for more information. | object | Recommended for intangible goods | Mandatory |
Pass the following fields when you send aCapture payment for order request
| Field name | Description | Type | Notes | Priority |
payment_source.card.number | The primary account number (PAN) for the payment card. See the parameter definition for more information. | string |
| Mandatory |
payment_source.card.name | The cardholder's name as it shows up on the card. See the parameter defintion for more information. | string |
| Mandatory |
payment_source.card.attributes.customer.email_address | Email address of the merchant as provided to the merchant or on file with the merchant. See the parameter definition for more information. | string |
| Mandatory |
payment_source.card.attributes.customer.phone | The phone number of the customer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number. See the parameter definition for more information. | object | Recommended | |
payment_source.card.billing_address | The billing address for the card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. See the parameter definition for more information. | object | Mandatory | |
PayPal-Client-Metadata-Id | A unique key that identifies risk data. See the parameter definition for more information. | string |
| Mandatory |
For Google or Apple Pay transactions, fields should be passed through the JavaScript SDK instead of Orders V2 API request. See Google Pay and Apple Pay integration guides for more details about setting up your integration. Pass the following fields through the SDK:
| Field name | Description | Priority |
Buyer credit card | The card number that includes the Device Primary Account Number (DPAN) and the credit card hash. | Mandatory |
Cardholder name | The cardholder's name. | Mandatory |
Buyer name | The buyer's name. | Recommended |
Buyer email | The buyer's email address. Ensure this entry is not null or –999. | Mandatory |
Buyer phone | The buyer's phone number. Ensure this entry is not null or –999. | Recommended |
Buyer billing address | Billing address for the transaction. Ensure address_line1 and address_city are not blank and contain a valid input. | Mandatory |
Buyer shipping address | This is the buyer's shipping address. Ensure address_line1 and address_city are not blank and contain a valid input. You may lose dispute eligibility and Chargeback Protection coverage if you don't provide a valid shipping address. | Mandatory for tangible goods and recommended for intangible goods |
RDA key | A unique key that identifies risk data. | Mandatory |
| Xclick item information | Contains information about the item purchased. | Recommended |
| Auto submit evidence for charegeback protection | Shipping ID, tracking ID, and additional evidence. See the Proof of delivery policy for more information. | Recommended |
To submit shipping or tracking information and any additional evidence as required by policy, see the following steps:
CUSTOMER.DISPUTE.CREATED webhook to receive a notification when a dispute is created. The payload includes the dispute.id.dispute.id to retrieve dispute details and determine the appropriate action.response.adjudications.reason.PROTECTION_POLICY_APPLIES. See Get started with PayPal REST APIs for dispute details.request.evidence-file path. See Get started with PayPal REST APIs to learn to upload evidence.