Payment Authorization

Payment Authorization is the process of requesting approval from Klarna. Klarna evaluates whether to approve a Payment Transaction and/or issue a customer token. The evaluation considers risk, fraud, and credit policies.

What is Payment Authorization

Payment Authorization is the process where Klarna evaluates and decides whether to approve a Payment Transaction and/or issue a customer token. You initiate this process by calling the authorizePayment API

endpoint, which serves as the entry point for all payment flows in Klarna's system. Based on real-time evaluation of risk, fraud, and credit policies, Klarna determines whether to immediately approve the payment, decline it, or request additional customer verification.

What Klarna evaluates:

Transaction details (amount, currency, purchase data, payment context)
Customer eligibility (credit, fraud, compliance checks)
Contextual signals (Klarna Network Session Token)

How it works:

Each call represents a distinct authorization attempt. Configuration determines available outcomes through step_up_config (allows customer interaction), request_payment_transaction (create a transaction) and request_customer_token (enables tokenization).

When you call the authorizePayment API

endpoint, Klarna produces different resource types based on the outcome. This makes the action an orchestrator that creates Payment Transaction, Customer Token, or Payment Request depending on the result.

Authorization initiation models

Payment Authorization supports two models based on customer presence:

Aspect	Customer-Initiated	Partner-Initiated
Common scenarios	E-commerce checkouts, real-time purchases	Subscription renewals, partner-initiated transactions
Customer presence	Required - customer can complete verification steps	Not present - uses saved credentials or token
Step-up configuration	Always include `step_up_config` (`HANDOVER` or `SDK` method)	Never include `step_up_config`
Credentials	Customer Token or Klarna Network Session Token (optional, recommended)	Customer Token or Klarna Network Session Token
Possible results	`APPROVED`, `DECLINED`, `STEP_UP_REQUIRED`	`APPROVED` or `DECLINED` only

Customer-initiated authorization

Always include step_up_config in customer-initiated scenarios. This allows Klarna to interact directly with the customer if needed.

How it works:

1.
Call authorizePayment with payment context (amount, currency, purchase data). Include Klarna Network Session Token if available.
2.
Configure step_up_config with HANDOVER (redirects to URL) or SDK (uses Klarna SDK).
3.
Optionally include request_customer_token to create a reusable token for future partner-initiated authorizations.
4.
Klarna returns APPROVED (Payment Transaction created), STEP_UP_REQUIRED (customer must complete Klarna Purchase Journey), or DECLINED (authorization failed).

If step-up is required, launch Klarna Purchase Journey. After completion, Klarna issues a new Klarna Network Session Token. Call authorizePayment API

again with this new token to complete the authorization.

Partner-initiated authorization

Never configure step_up_config for partner-initiated authorization, since the customer is not present for this initiation model.

How it works:

1.
Call authorizePayment with payment context (amount, currency, purchase data).
2.
Include Customer Token (created during previous customer-initiated authorization) or Klarna Network Session Token received from the partner.
3.
Klarna evaluates using risk models appropriate for customer-not-present scenarios.
4.
Result is either APPROVED (Payment Transaction created) or DECLINED.

Authorization results and resource creation

The authorization action returns one of three results, each leading to different outcomes and resource creation.

flowchart TD Start[authorizePayment] Eval{ } Start --> Eval Eval --> Approved[APPROVED] Eval --> Declined[DECLINED] Eval --> StepUp[STEP_UP_REQUIRED] Approved --> PT[Payment Transaction resource created] Declined --> Nothing[No Resource Created] StepUp --> PR[Payment Request resource created] PR --> NewSessionToken[Klarna Network Session Token issued] NewSessionToken --> Reauth[authorizePayment with Klarna Network Session Token] Reauth --> PT

Result	What Happens	Resource Created	Next Steps
`APPROVED`	The authorization succeeded. Klarna created a Payment Transaction, Customer Token, or both depending on the request.	Payment Transaction and/or Customer Token	Store the `payment_transaction_id` and/or `customer_token_id`. Proceed with subsequent actions.
`DECLINED`	The authorization failed. A `result_reason` indicates the cause. Failure results from risk, fraud, credit policy, or other evaluation criteria.	None	Display error message to customer. Do not retry without specific guidance from Klarna.
`STEP_UP_REQUIRED`	Additional customer interaction is needed. This result only occurs when `step_up_config` is provided in the request.	Payment Request	Launch Klarna Purchase Journey for the customer. Wait for completion. Call authorizePayment again with the new Klarna Network Session Token issued after completion.

Result: APPROVED

Payment Transaction and/or Customer Token created. Store the resource IDs and proceed with post-purchase actions (capture, void, refund).

The response includes payment_transaction_response (if Payment Requested) and/or customer_token_response (if tokenization requested) with result: APPROVED.

Sample response:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:us1:transaction:6debe89e-98c0-[...]",
      "payment_transaction_reference": "transaction-reference-1234",
      "amount": 11800,
      "currency": "USD",
      "state": "AUTHORIZED",
      "payment_funding": {

Result: STEP_UP_REQUIRED

Payment Request created. Launch Klarna Purchase Journey for the customer. After completion, call authorizePayment API

again with the new Klarna Network Session Token.

The response includes payment_request with details for launching the customer interaction.

Sample response:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    "payment_request_id": "krn:payment:us1:request:552603c0-fe8b-[...]",
    "payment_request_reference": "acquiring-partner-request-reference-1234",
    "amount": 11800,
    "currency": "USD",
    "state": "SUBMITTED",

Next steps:

Launch Klarna Purchase Journey using the method specified in your step_up_config (HANDOVER or SDK). After the customer completes the Klarna Purchase Journey, Klarna issues a new Klarna Network Session Token. Call authorizePayment API

again with this new token to complete the authorization.

Result: DECLINED

No resources created. Display an error message to the customer. Do not retry without changes or guidance from Klarna.

The response includes result: DECLINED with result_reason indicating the cause.

Sample response:

JSON

1 2 3 4 5 6

{
  "payment_transaction_response": {
    "result": "DECLINED",
    "result_reason": "PAYMENT_DECLINED"
  }
}

Resource interactions

Payment Authorization operates as an orchestrator, consuming optional input resources and creating output resources based on the evaluation outcome.

Resources consumed (optional)

Klarna Network Session Token is issued by Klarna after customer interactions with Conversion features or can be received from the partner. It preserves customer context from Express Checkout and messaging interactions, optimizing the customer experience. When present, authorization is more likely to be approved without step-up.

The token is used in both initiation models. In customer-initiated scenarios, it reduces step-up requirements. In partner-initiated scenarios, it can authorize payments without a Customer Token. After Klarna Purchase Journey completion, Klarna issues a new token for the subsequent authorization call.

Customer Token is used for partner-initiated authorization without customer presence. It represents customer consent for future charges. Create customer tokens during customer-initiated authorization by including request_customer_token, then use them in subsequent partner-initiated authorizations.

Resources created

Payment Transaction is created when authorization is APPROVED. It represents the authorized payment and supports capture, void, or refund actions. The resource contains amount, currency, funding details, and pricing information, and progresses through various states during post-purchase actions.

Customer Token is created when tokenization is requested and approved. Request tokenization during customer-initiated authorization by including request_customer_token. The token enables future partner-initiated payments and contains the identifier and scopes (payment:customer_present or payment:customer_not_present). See the Payment Tokenization deep dive article for detailed information.

Payment Request is created when the result is STEP_UP_REQUIRED. It manages the customer's Klarna Purchase Journey and contains details for launching customer interaction based on the step_up_config method, plus expiration time and configuration.

When the customer completes the Klarna Purchase Journey, the Payment Request transitions to COMPLETED. Klarna issues a new Klarna Network Session Token. Call authorizePayment API

again with this token to create the Payment Transaction and/or Customer Token.

Actors in the authorization flow

Payment Authorization involves multiple actors working together to evaluate and complete payments. Understanding each actor's role is essential for implementing a compliant integration.

sequenceDiagram autonumber participant Customer participant Partner participant Acquiring Partner participant Klarna Customer->>Partner: Initiates checkout Partner->>Partner: Collects payment data Uses Klarna SDK for Boost Partner->>Acquiring Partner: Sends Payment Request Acquiring Partner->>Klarna: authorizePayment (with Klarna Network Session Token, payment details) Klarna->>Klarna: Evaluates: - Risk, fraud, credit - Customer eligibility - Contextual signals alt Authorization APPROVED Klarna->>Acquiring Partner: APPROVED result Payment Transaction created Acquiring Partner->>Partner: Payment success Partner->>Customer: Payment confirmation else Step-up required Klarna->>Acquiring Partner: STEP_UP_REQUIRED result Payment Request created Acquiring Partner->>Partner: Requires customer interaction Partner->>Customer: Launch Purchase Journey Customer->>Klarna: Completes Purchase Journey Klarna->>Klarna: Issues new Klarna Network Session Token Klarna->>Partner: Payment Request completed New Klarna Network Session Token issued Partner->>Acquiring Partner: Retry payment with new Klarna Network Session Token Acquiring Partner->>Klarna: authorizePayment (with new Klarna Network Session Token) Klarna->>Klarna: Creates Payment Transaction Klarna->>Acquiring Partner: APPROVED result Payment Transaction created Acquiring Partner->>Partner: Payment success Partner->>Customer: Payment confirmation else Authorization DECLINED Klarna->>Acquiring Partner: DECLINED result Acquiring Partner->>Partner: Payment failed Partner->>Customer: Error message end

Actor responsibilities

Actor	Key Responsibilities
Customer	Completes purchase and provides payment information. Completes Klarna Purchase Journey when step-up is required. Not actively present in partner-initiated scenarios.
Partner	Provides customer-facing checkout experience. Integrates Klarna SDK for Boost features and token collection. Forwards Payment Requests to Acquiring Partner. Launches Klarna Purchase Journey for step-up scenarios.
Acquiring Partner	Calls authorizePayment on behalf of Partners. Processes authorization results. Manages Payment Request workflows when step-up is required. Orchestrates post-purchase actions. Implements correct authorization scenario based on customer presence.
Klarna	Evaluates authorization requests (transaction details, customer eligibility, risk, fraud, credit, compliance). Issues Klarna Network Session Tokens via SDK and after Klarna Purchase Journey completion. Creates resources (Payment Transaction, Customer Token, Payment Request). Manages resource lifecycle.

Klarna Network Session Token

Payment transaction state definitions

Customer Token

Payment Request

Payment Tokenization