> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.
# PayPal
> View and resolve PayPal disputes from the inbox customer panel and with AI Agents.
The PayPal integration lets your team handle PayPal disputes without leaving Chatarmin CX. When a ticket contact's email matches a dispute buyer on a connected PayPal account, disputes appear in the customer panel so agents can review the case and respond in context.
PayPal disputes appear in the **customer panel** on a ticket. They do not create separate inbox tickets or email notifications from PayPal.
## When to use it
Use PayPal when you accept PayPal payments and your support team regularly handles:
* chargebacks and payment disputes
* buyer claims about items not received or not as described
* evidence deadlines and offers before a case escalates
The integration keeps ticket context, customer history, and dispute details in one place instead of switching to the [PayPal Resolution Center](https://www.paypal.com/disputes/) in another tab.
## Set up PayPal
You need a PayPal REST app with **Disputes** enabled. Create or open the app in the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard/).
[Open integrations](https://armin.cx/app/_/settings/integrations) from your workspace settings and choose **PayPal**.
If PayPal is not listed, contact your Chatarmin CX account team to enable it for your workspace.
Click **Connect**, enter an optional display name (helpful when you connect more than one merchant account), then paste the **Client ID** and **Client Secret** from your REST app.
Repeat **Connect** for each PayPal merchant account your team manages. Each account syncs its own disputes.
Use a clear display name such as `EU storefront PayPal` when you connect multiple accounts so agents know which merchant account a dispute belongs to.
## Use PayPal in the inbox
When PayPal is connected and the ticket contact has an email address, cx matches that email to indexed PayPal disputes for your organization.
1. Open a ticket with a contact that has an email address.
2. In the **customer panel**, find the **Disputes** section when matching disputes exist for that contact.
3. Click a dispute to open the detail sheet with case status, amount, timeline, messages, and evidence requests.
4. Use **Respond to dispute** to take the actions PayPal allows for that case state — for example send a message, make an offer, provide evidence, escalate, accept a claim, appeal, or acknowledge a returned item.
5. Use **Open in PayPal Resolution Center** when you need the full PayPal UI.
Resolved disputes stay visible in the list so agents can see past cases for the same customer.
### How disputes stay up to date
cx indexes disputes from PayPal when they are created or updated. A background sync also runs every few hours to pick up cases that changed outside cx. After you act on a dispute in cx, the case refreshes automatically.
### Matching disputes to contacts
Disputes are linked by **buyer email**. The contact's primary email and any other email identifiers on the contact are used for matching.
| Situation | What you see |
| ----------------------------------- | -------------------------------------------------- |
| PayPal not connected | No Disputes section |
| Contact has no email | Add an email to the contact to search for disputes |
| Email present, no matching disputes | Disputes section stays hidden |
| Email matches one or more disputes | Disputes section lists open and resolved cases |
## Inbox dispute actions
Available actions depend on the dispute's current state. PayPal controls which responses are allowed at each stage.
| Action | Typical use |
| ------------------------- | ----------------------------------------------------- |
| Send message | Reply to the buyer in the dispute thread |
| Make offer | Propose a refund, replacement, or other resolution |
| Provide evidence | Submit notes and supporting files PayPal requested |
| Escalate to claim | Move the case forward when negotiation fails |
| Accept claim | Accept the loss when you will not contest the dispute |
| Appeal | Challenge a decision after adjudication |
| Acknowledge returned item | Confirm you received a return the buyer shipped |
**Accept claim** and some offers can move money. cx asks for confirmation before destructive inbox actions. Double-check amount and offer type before submitting.
### Evidence files
When PayPal requests evidence, you can attach files from your computer when submitting from the inbox. Supported formats are PDF, PNG, JPG, and GIF. Each file can be up to 10 MB, with a 50 MB total per request. Notes are limited to 2,000 characters.
## AI Agent actions
Give an [AI Agent](/ai-agents/skills-and-actions) PayPal actions when you want automation to look up disputes or draft responses on dispute-related tickets. The agent must run on a ticket with a contact that has an email address.
Connect PayPal first, then enable actions on the agent and select which connected PayPal account(s) the agent may use.
### Read actions
* **List PayPal disputes** — Find indexed disputes for the ticket contact's email.
* **Get PayPal dispute** — Load full live dispute detail before taking a write action. Always use this after listing disputes.
### Write actions
* **Send message** — Reply in the dispute thread.
* **Make offer** — Propose a resolution.
* **Provide evidence** — Submit evidence and optional attachments from customer messages on the ticket.
* **Escalate** — Escalate to claim when allowed.
* **Accept claim** — Accept the dispute loss.
* **Appeal** — File an appeal when allowed.
* **Acknowledge returned item** — Confirm receipt of a return.
Financial write actions such as **Accept claim** and **Make offer** require [human approval](/ai-agents/human-in-the-loop) by default. Adjust approval settings per action when you configure the agent.
In agent instructions, tell the agent to list disputes first, call **Get PayPal dispute** for the case it will act on, and only use offer or accept types that appear in the live dispute detail.
## Best practices
* Keep the contact email aligned with the email the customer used on PayPal. Update the contact if they wrote from a different address.
* Use display names when you connect multiple PayPal accounts so agents and AI Agents pick the right integration.
* Require approval on money-moving actions until you trust the agent's dispute playbook.
* Test with PayPal's sandbox app and credentials in a non-production workspace before going live.
* For complex cases, use cx for context and the Resolution Center link when PayPal-only steps are required.
## Troubleshooting
### Connection test fails
* Confirm the REST app has **Disputes** enabled in the PayPal Developer Dashboard.
* Check that the Client ID and Client Secret are from the same app and environment (live vs sandbox).
* Rotate the secret in PayPal if it was revoked, then update the integration in cx.
### No disputes for a customer
* Verify the contact email matches the buyer email on the PayPal dispute.
* Allow time for indexing after connect — new and updated disputes sync automatically; the periodic reconcile can take up to a few hours for edge cases.
* Confirm the dispute belongs to a PayPal account you connected in this workspace.
### An action is unavailable
PayPal only allows certain responses for each dispute state. Open dispute detail in cx or in the Resolution Center to see what is permitted. If the case was updated in PayPal outside cx, refresh by closing and reopening the dispute sheet.