# How to Test Klarna Payments

This guide shows how to create a payment request that launches Bead’s hosted checkout page, select Klarna in the UI, complete the Sandbox checkout using Klarna test credentials, and verify the result.

#### 1 – Prerequisites

| Item                                                  | Notes                                                                                  |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Klarna enabled for your Sandbox merchant and terminal | Contact developer support if Klarna is not yet activated for your Sandbox environment. |
| Sandbox base URL                                      | `https://api.test.devs.beadpay.io`                                                     |
| Hosted payment page base                              | Returned in `paymentUrls`                                                              |
| Terminal API key                                      | You need the real API key value. The masked API key is not usable.                     |
| `merchantId` and `terminalId`                         | Must match the terminal API key you were issued.                                       |
| Webhook endpoint (recommended)                        | Publicly reachable and registered in the Bead dashboard.                               |

Authentication note: Payments endpoints use header-based authentication. Send your API key as `X-Api-Key` on every request.

#### 2 – Create Payment Request

Send a `POST /Payments/crypto` to generate the hosted checkout URL.

Required headers:

* `X-Api-Key: {apiKey}`
* `Content-Type: application/json`

Klarna testing requires customer details in the request. Minimum required fields depend on the terminal `type`:

| Terminal `type` | Required fields                                                              |
| --------------- | ---------------------------------------------------------------------------- |
| `virtual`       | `merchantId`, `terminalId`, `requestedAmount`, `refundEmail`, and `customer` |
| `physical`      | `merchantId`, `terminalId`, `requestedAmount`, and `customer`                |

The `customer` object should include:

* `firstName`
* `lastName`
* `email`
* `address`
* `address2`
* `city`
* `state`
* `postalCode`
* `countryCode`

**Example request for terminal `type` = `virtual`**

```bash
curl -s -X POST "https://api.test.devs.beadpay.io/Payments/crypto" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": 1,
    "refundEmail": "alex.tester@example.com",
    "customer": {
      "firstName": "Jordan",
      "lastName": "Reed",
      "email": "jordan.reed@example.com",
      "address": "456 Market St",
      "address2": "Suite 210",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601",
      "countryCode": "US"
    }
  }'
```

**Example request for terminal `type` = `physical`**

```bash
curl -s -X POST "https://api.test.devs.beadpay.io/Payments/crypto" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {apiKey}" \
  -d '{
    "merchantId": "{merchantId}",
    "terminalId": "{terminalId}",
    "requestedAmount": 1,
    "customer": {
      "firstName": "Taylor",
      "lastName": "Brooks",
      "email": "taylor.brooks@example.com",
      "address": "88 Lakeview Ave",
      "address2": "",
      "city": "Denver",
      "state": "CO",
      "postalCode": "80202",
      "countryCode": "US"
    }
  }'
```

Example response:

```json
{
  "trackingId": "c10b29e3c...",
  "paymentPageId": "6539fa89f0363f1722b377ef",
  "paymentUrls": [
    "https://pay.test.devs.beadpay.io/6539fa89f0363f1722b377ef"
  ]
}
```

Save these values:

* `paymentUrls[0]` for the hosted checkout URL
* `trackingId` to check status
* `paymentPageId` for support and troubleshooting

#### 3 – Launch Hosted Payment Page

Use `paymentUrls[0]` to launch checkout.

| Option   | Details                                                 |
| -------- | ------------------------------------------------------- |
| Redirect | Redirect the shopper’s browser to the hosted page URL.  |
| Embed    | Load the hosted page URL in an iframe inside your site. |

The shopper now sees Bead’s hosted payment page.

#### 4 – Select Klarna and Open Klarna Checkout

1. In the Bead hosted UI, select Klarna as the payment method.
2. Bead displays a Klarna QR code linked to Klarna’s Sandbox checkout.

How the tester can open Klarna checkout:

* Scan the QR code with a phone camera to open Klarna in the mobile browser.
* Click or tap the QR code to copy the Klarna checkout URL, then paste it into any browser.

#### 5 – Complete Klarna Sandbox Checkout

Use the following test values in Klarna’s Sandbox flow.

| Field             | Test value                            |
| ----------------- | ------------------------------------- |
| Phone number      | `716-220-4669`                        |
| PIN (if prompted) | `123456`                              |
| Card number       | `4111 1111 1111 1111`                 |
| Card expiry       | Any future MM/YY, for example `12/29` |
| Card CVV          | `123`                                 |

Follow Klarna’s prompts until the shopper is returned to your `redirectUrl`, if you provided one.

#### 6 – Verify Result

You can verify completion using webhooks and, optionally, an API status check.

**Option A: Webhook verification**

Confirm your webhook endpoint receives a payment event indicating completion. Look for a status field that indicates the payment is completed.

**Option B: API status check (optional)**

Use the same terminal API key approach as `POST /Payments/crypto`.

Endpoint: `GET /payments/tracking/{trackingId}`

Example curl:

```bash
curl -s -X GET "https://api.test.devs.beadpay.io/payments/tracking/{trackingId}" \
  -H "X-Api-Key: {apiKey}" \
  -H "Accept: application/json"
```

What to confirm:

* The response shows the payment in a completed state.
* Amount fields reflect a successful payment for the requested amount.

#### Troubleshooting

Common issues:

* Klarna does not appear as a tender option\
  Klarna may not be enabled for the Sandbox merchant or terminal. Confirm enablement with developer support.
* `401 Unauthorized`\
  The API key is missing or invalid, or the header name is wrong. The header must be exactly `X-Api-Key`.
* `403 Forbidden`\
  The API key is valid but not permitted for the `merchantId` or `terminalId` in your request. Confirm the IDs match the credential set you were issued and that you are using the correct environment.
* Validation error on payment creation\
  Confirm you are using the correct minimum request shape for the terminal `type`. Terminals with `type` = `virtual` require `refundEmail`; terminals with `type` = `physical` do not. Both terminal types require the `customer` object for Klarna testing.
* Redirect does not happen\
  Confirm you set a valid `redirectUrl`. If not provided, Bead will display a hosted confirmation screen instead of redirecting.

#### 7 – Next Steps

* Test different amounts and run cancellation or expiry scenarios.
* Validate your production readiness using webhooks plus status checks and avoid tight polling loops.
* Update related payment examples to reflect terminal-type-specific minimum request fields where Klarna is supported.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/how-to-test-klarna-payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.