Skip to main content
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 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.
1

Open integrations

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

Connect an account

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

Connect additional accounts (optional)

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.

​
Inbox dispute actions

Available actions depend on the dispute’s current state. PayPal controls which responses are allowed at each stage.
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 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 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.