> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Klarna

> Let your chatbot answer customer payment questions

Enable your AI chatbot to answer Klarna payment questions, check order status, and help customers track refunds through natural conversation.

## Why Connect Klarna?

* **Instant Payment Answers**: Customers get payment status, order info, and refund details immediately
* **BNPL Support**: Handle Pay Later, Pay in 3/4, and Financing questions automatically
* **Reduced Support Tickets**: Deflect 70%+ of common payment questions automatically
* **Secure by Default**: Read-only access with email verification for each lookup

## Prerequisites

Before connecting, you'll need:

* A Klarna merchant account with API access
* Admin access to create API credentials in Klarna Merchant Portal

## Setup Steps

### Step 1: Get Your Klarna API Credentials

<Steps>
  <Step title="Open Klarna Merchant Portal">
    Go to [Klarna Merchant Portal](https://portal.klarna.com) and log in

    <Note>
      For testing, use the [Klarna Playground Portal](https://portal.playground.klarna.com) instead.
    </Note>
  </Step>

  <Step title="Navigate to API Credentials">
    Go to **Settings** → **API Credentials** → **Generate new Klarna API credentials**
  </Step>

  <Step title="Download Credentials File">
    Download the credentials file when prompted. This file contains:

    * **API Username**: Your API username from Klarna
    * **API Password**: The API password (only shown once)

    <Warning>
      Store this file securely—the password is only shown once and cannot be retrieved later.
    </Warning>
  </Step>

  <Step title="Note Your Region">
    Note which region your Klarna account is in:

    * **EU** (Europe)
    * **NA** (North America)
    * **OC** (Oceania/Australia)
  </Step>
</Steps>

### Step 2: Connect to BubblaV

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Dashboard** → **Integrations** → **Klarna**
  </Step>

  <Step title="Enter API Username">
    Paste the **API Username** from your credentials file
  </Step>

  <Step title="Enter API Password">
    Paste the **API Password** from your credentials file
  </Step>

  <Step title="Select Region">
    Choose your Klarna API region (EU, NA, or OC)
  </Step>

  <Step title="Enable Test Mode (if testing)">
    If using credentials from [Klarna Playground Portal](https://portal.playground.klarna.com), enable the **Test Mode** checkbox to use sandbox API
  </Step>

  <Step title="Connect">
    Click **Connect** to validate credentials and enable payment tools
  </Step>
</Steps>

***

## Available Tools

Once connected, these tools become available to your chatbot:

| Tool                         | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| **Get Order Status**         | Order status, total amount, and creation date                 |
| **Get Payment Status**       | Whether the payment is UNPAID, PAID, or CLOSED                |
| **Get Refund Status**        | Refund amounts and processing details                         |
| **Get Payment Info**         | Payment method type and installment schedule                  |
| **Get Order History**        | List of customer's Klarna orders                              |
| **Get Payment Methods**      | Available Klarna payment options                              |
| **Get Installment Schedule** | Detailed breakdown of Pay in 3/4 installments with due dates  |
| **Get Upcoming Payments**    | List of pending payments with "days until due" context        |
| **Get Capture Details**      | Shows what's been charged vs. pending (for partial shipments) |

***

## How It Works

1. **Customer asks a payment question** (e.g., "Is my Klarna payment complete?")
2. **Customer provides order reference** and email for verification
3. **AI verifies customer** by matching email to the order's billing address
4. **Data is retrieved** securely from Klarna's API
5. **Formatted response** is provided with payment status and details

<Note>
  Customer verification uses email matching. The chatbot only provides payment information when the provided email matches the billing email on the Klarna order.
</Note>

<Warning>
  Unlike some integrations, Klarna's API requires a Klarna Order ID (UUID format) for lookups. If using Shopify with the Klarna OSM app, this is extracted automatically. Otherwise, customers need to provide it from their Klarna app or email.
</Warning>

***

## Shopify Integration

For the best experience with Shopify stores, we recommend installing the **Klarna On-site Messaging (OSM) app** with Extended Access enabled.

<Tip>
  When Extended Access is enabled, the Klarna Order ID is automatically added to Shopify order notes, allowing our chatbot to seamlessly look up Klarna payment information without requiring customers to manually provide their Order ID.
</Tip>

### Enable Extended Access

<Steps>
  <Step title="Install Klarna OSM App">
    Install the [Klarna On-site Messaging app](https://apps.shopify.com/klarna-on-site-messaging) from the Shopify App Store
  </Step>

  <Step title="Enable Extended Access">
    In the OSM app settings, ensure **Extended Access** is enabled. This is on by default.
  </Step>

  <Step title="Benefits of Extended Access">
    * Klarna Order ID is automatically added to Shopify order notes
    * A "Klarna" tag is added to orders placed through Klarna
    * Product images and URLs are synced to the Klarna app for customers
  </Step>
</Steps>

<Note>
  If the Klarna Order ID is not available (e.g., OSM not installed or Extended Access disabled), the chatbot will ask the customer to provide their Klarna Order ID (UUID format) from their Klarna app or confirmation email.
</Note>

***

## Security

* **Read-only access**: No changes to orders or payments—information only
* **Email verification**: Customers must be verified before accessing payment data
* **Encrypted credentials**: API keys are encrypted at rest
* **GDPR compliant**: We follow EU data protection requirements
* **Regional API support**: Data stays within your configured region

***

## FAQs

<AccordionGroup>
  <Accordion title="What Klarna permissions are required?">
    You need read access to the Order Management API. This provides access to order details, payment status, captures, and refunds without allowing any modifications.
  </Accordion>

  <Accordion title="How are customers verified?">
    Customers provide their order reference number and email. The chatbot verifies that the email matches the billing address on the Klarna order before showing any payment information.
  </Accordion>

  <Accordion title="Can customers search orders by email only?">
    No. Due to Klarna API limitations, a Klarna Order ID is required for lookups. With Shopify + Klarna OSM, this is extracted automatically. Otherwise, the chatbot guides customers to find it in their Klarna app or confirmation email.
  </Accordion>

  <Accordion title="Which Klarna regions are supported?">
    We support all Klarna regions: EU (Europe), NA (North America), and OC (Oceania/Australia). Select the correct region when configuring the integration.
  </Accordion>

  <Accordion title="Is my Klarna data secure?">
    Yes. We use Klarna's official API with encrypted credentials. Your API key is never exposed, and we comply with GDPR and industry security standards.
  </Accordion>

  <Accordion title="Can I use test credentials?">
    Yes! Enable **Test Mode** when connecting to use Klarna Playground API for testing. Use credentials from [portal.playground.klarna.com](https://portal.playground.klarna.com) to test the integration before going live.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

### "Invalid credentials" Error

* Verify the API Username is correct
* Check that the API Password is correct
* Ensure you selected the correct region (EU, NA, or OC)
* Verify credentials haven't been revoked in Klarna Merchant Portal

### "Order not found" Response

* Verify the order reference number is correct
* The order must exist in your Klarna merchant account
* For very recent orders, wait a few minutes for API sync

### "Email verification failed"

* The email provided must exactly match the order's billing email
* Check for typos or different email addresses
* Email matching is case-insensitive

### Tools Not Appearing

* Verify the integration status is "Connected"
* Check that tools are enabled in **Configure** → **Tools**
* Refresh your integrations page

***

## Example Conversations

Here are examples of how customers can interact with your chatbot:

**Checking payment status:**

> Customer: "Is my Klarna payment complete?"
> Bot: "Let me check that for you. What's your order reference number?"
> Customer: "ORD-12345"
> Bot: "I found your order. ✅ Your payment is complete. Total paid: SEK 1,200.00 via Pay in 3."

**Checking refund status:**

> Customer: "Has my refund been processed?"
> Bot: "I can check that for you. What's your order number and the email address on the order?"
> Customer: "Order ABC123, email is [anna@example.com](mailto:anna@example.com)"
> Bot: "Yes, your refund of SEK 299.00 was processed on December 15, 2024."

**Understanding payment options:**

> Customer: "What Klarna payment options do you offer?"
> Bot: "We offer these Klarna options:
> • Pay Later: Pay the full amount within 30 days
> • Pay in 3: Split into 3 interest-free payments
> • Financing: Flexible monthly payments"

**Checking installment schedule:**

> Customer: "When are my Klarna payments due?"
> Bot: "Here's your installment schedule for order ORD-12345:
> ✅ #1: SEK 400.00 - Due: Dec 1 (Paid)
> ⏳ #2: SEK 400.00 - Due: Jan 1
> ⏳ #3: SEK 400.00 - Due: Feb 1"

**Checking upcoming payments:**

> Customer: "When is my next Klarna payment?"
> Bot: "Your next payment is SEK 400.00 due on January 1 (in 10 days). You have one more payment of SEK 400.00 due February 1."

**Understanding partial charges:**

> Customer: "Why was I only charged for part of my order?"
> Bot: "I can see that SEK 600.00 of your SEK 1,200.00 order has been captured so far. This typically happens when items ship separately. The remaining SEK 600.00 will be charged when the rest of your order ships."