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