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

# Klarna

> Manage Klarna payment disputes from the inbox while you help the customer on the same ticket.

The Klarna integration lets your team view and respond to Klarna payment disputes from the ticket sidebar — next to the customer conversation — instead of switching to the Klarna Merchant Portal.

## When to use it

Use Klarna in Chatarmin CX when:

* customers pay with Klarna and you receive chargebacks, claims, or evidence requests
* agents need order context and ticket history beside dispute details
* you want AI Agents to look up disputes, draft evidence, or propose dispute actions with human approval

<Note>
  Klarna disputes appear in the inbox **Disputes** panel on a ticket. They are not imported as separate Klarna notification emails.
</Note>

## Set it up

You need Klarna **Disputes API** credentials (API username and password) for each merchant account you connect. Your Klarna account must be enabled for dispute management.

<Steps>
  <Step title="Open integrations">
    Go to [Integrations](https://armin.cx/app/_/settings/integrations) and select **Klarna**.
  </Step>

  <Step title="Connect a merchant account">
    Click **Connect**, enter a display name (optional), and add your Klarna API username and password. You can connect **multiple Klarna accounts** per workspace — for example, one per storefront or region.
  </Step>

  <Step title="Test the connection">
    After saving, use **Test connection** on the account card to confirm credentials work.
  </Step>
</Steps>

When you connect, Chatarmin CX **automatically registers dispute webhooks** for your account — you do not need to configure webhooks yourself. Automatic setup only works when Klarna has already enabled webhook access for your merchant account. If your account does not have that access yet, ask your Klarna contact to enable it, then reconnect or edit the integration.

<Note>
  If automatic webhook registration is unavailable for your account, the integration dialog may show **Webhook setup required** with manual fields. That path is only for merchants Klarna has not yet granted webhook API access.
</Note>

<Tip>
  Connecting Shopify helps Chatarmin CX match disputes to customers when Klarna does not include a buyer email. Link the customer's email on the contact when disputes do not appear.
</Tip>

## Use Klarna disputes in the inbox

When a ticket contact has an email address and a matching Klarna dispute exists, the **Disputes** section in the customer panel lists Klarna cases for that customer — including resolved disputes.

<Steps>
  <Step title="Open a ticket">
    Open the ticket for the customer who filed or is affected by the dispute.
  </Step>

  <Step title="Confirm the contact email">
    The contact needs an email address. If none is set, add one — disputes are matched by email.
  </Step>

  <Step title="Review disputes">
    In **Disputes**, open a Klarna row to see reason, stage, amount, response deadline, activity, order references, and evidence requests.
  </Step>

  <Step title="Respond">
    Use the action form at the bottom of the dispute detail sheet. Available actions depend on the dispute stage.
  </Step>
</Steps>

### Actions you can take

| Action               | What it does                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| **Provide evidence** | Submit your response to Klarna with required details, optional partial refund, and PDF proof. |
| **Accept claim**     | Accept the loss on the dispute. This is irreversible and may debit your account.              |
| **Appeal**           | Submit a text-only appeal during pre-arbitration when Klarna allows it.                       |

Klarna does not support in-dispute messaging, settlement offers, or escalation actions that PayPal provides. Use **Send reply** on the ticket to communicate with the customer separately.

### Evidence file rules

When Klarna asks for proof:

* upload **PDF only**
* maximum **7 MB** per file
* up to **10** files per submission
* add a short description for each file

Some dispute reasons ask extra questions — for example whether the order shipped, tracking details, or whether a return was received. The form shows only the fields Klarna requires for that case.

## AI Agent actions

Give a dispute-handling AI Agent Klarna actions so it can work inside the ticket:

| Action                              | Purpose                                                        |
| ----------------------------------- | -------------------------------------------------------------- |
| **List Klarna disputes**            | Find indexed disputes for the ticket contact's email.          |
| **Get Klarna dispute**              | Load live dispute detail and see which actions are allowed.    |
| **Provide Klarna dispute evidence** | Submit representment with PDF attachments from the ticket.     |
| **Accept Klarna dispute claim**     | Propose accepting the loss — **requires approval** by default. |
| **Appeal Klarna dispute**           | Submit a text appeal when the dispute is in pre-arbitration.   |

<Steps>
  <Step title="Connect Klarna">
    Complete the integration setup above.
  </Step>

  <Step title="Enable actions on the agent">
    In [AI Agents](https://armin.cx/app/_/ai/agents-v2), open the agent and enable the Klarna actions the job needs. Select which connected Klarna account(s) the agent may use.
  </Step>

  <Step title="Set approvals">
    Keep **Accept Klarna dispute claim** on **Always require approval**. Partial refund proposals on **Provide evidence** also pause for approval before they run.
  </Step>

  <Step title="Add instructions">
    Tell the agent to call **Get Klarna dispute** before any write, use order data from Shopify or your fulfillment integration for tracking fields, and use **Send reply** for customer-facing updates — not Klarna dispute messaging.
  </Step>
</Steps>

You can also trigger agents when a new or updated dispute is indexed. Use the **Dispute indexed** trigger and filter by provider **Klarna** and statuses such as **Needs your response**.

## Best practices

* Resolve disputes before the **response due** date shown in the detail sheet.
* Keep the contact email aligned with the Klarna order's billing email so disputes appear on the right ticket.
* Gather PDF proof (invoice, delivery confirmation, return policy) before opening **Provide evidence**.
* Use a clear display name when you connect multiple Klarna accounts so agents pick the right one.
* For sensitive financial actions, require human approval on the AI Agent even when the default is optional.

## Troubleshooting

| Symptom                                   | What to check                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Klarna does not appear under Integrations | Your workspace may not have Klarna enabled yet. Contact [support](mailto:support@chatarmin.com).                                                                                         |
| **Disputes** section is empty             | Confirm Klarna is connected, the contact has an email, and a dispute exists for that email. New connections can take up to a few hours for the first background sync.                    |
| Dispute exists in Klarna but not in cx    | Buyer email may not be enriched yet. Ensure Shopify is connected or the billing email matches the contact. Wait for the next sync cycle.                                                 |
| Disputes do not update in near real time  | Confirm Klarna enabled webhook access for your merchant account. Without it, disputes still sync on a periodic background schedule, but updates may be slower.                           |
| **Webhook setup required** appears        | Your account may not have Klarna webhook API access yet. Contact Klarna to enable it, then reconnect. Manual webhook fields are only shown when automatic registration is not available. |
| Evidence upload fails                     | Use PDF only, stay under 7 MB per file, and fill every required field on the form.                                                                                                       |
| **Test connection** fails                 | Verify API username and password in the [Klarna merchant portal](https://portal.klarna.com) and that Disputes API access is enabled for the account.                                     |