API & SDKsSupport

Klarna Partner Product API - Payment (v2/r6)

Download OpenAPI specification:Download

Full set of resources to manage the end-to-end lifecycle of a payment.

Payment Authorize API

The Payment Authorize API allows you to authorize payment transactions.

Authorize a payment transaction.

Authorize a payment transaction

SLO Category: The SLO Service Category. Operations that process payments for tokenized customers, including recurring and on-demand transactions.Customer Token Charge
SLA Service Class: The SLA Service Class this operation is classified at when evaluating SLA compliance. Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
Lifecycle Stage: The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
Availability in Test environment: Indicates if the feature is available in the Klarna Test environment Feature is available in the Klarna Test environmentAvailable
Availability in Production environment: Indicates if the feature is available in the Klarna Production environment Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only

Securityklarna_api_key and klarna_partner_account
Request
path Parameters
partner_account_id
required
string (accounts.model_AccountIdentifier)

Identifier of the Account the action is done on behalf of

Example: krn:partner:global:account:live:LWT2XJSE
validation-info: Validation that is a valid krn
header Parameters
Klarna-Idempotency-Key
string (KlarnaIdempotencyKey) [ 1 .. 255 ] characters

This header ensures operation idempotency. Use a unique key, ideally a UUID (version 4 or higher). Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts.

Klarna-Interoperability-Token
string (InteroperabilityToken)

The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wcGluZ19zZXNzaW9uX2lkIjoia3JuOnNob3BwaW5nOmV1MTpzZXNzaW9uOjBlOTIyN2MwLTBjNDAtNDdkZi04YzEwLTQwMTRmYzFiZDJiZCIsInN0YXR1cyI6IlBBWU1FTlRfUFJFUEFSRUQiLCJ2ZXJzaW9uIjoxLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0wMVQxMjowMDowMFoiLCJ1cGRhdGVkX2F0IjoiMjAyNC0wMS0wMVQxMjowMDowMFoifQ.1y87kuEKnETy_UCHbTMXx1p4mViZE816okcVmfHFZoo
Klarna-Payment-Token
string (PaymentToken) [ 1 .. 255 ] characters

The payment token represents a customer approval for payment.

It is issued when a Klarna Payment Request is completed.

Example: krn:payment:eu1:payment-token:e15432a5-ebcc-45bc-934c-e61399db597b
validation-info: Field must be between 1 and 255 characters in length (inclusive)
required
object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]
Request Body schema: application/json
required
currency
required
string (Currency) ^[A-Za-z]{3}$

Currency in ISO 4217 format.

validation-info: There is validation that the provided value is a valid currency. There is no validation that the we have pricing for the given currency.
interoperability_data
string <serialized-json> (InteroperabilityData) [ 1 .. 10240 ] characters

This field should be used for any additional interoperability data sent by your Integrating Partner.

validation-info: Field interoperability_data must be between 1 and 10240 characters in length (inclusive)
object (SupplementaryPurchaseData)

Additional information that provide more detailed information about the transaction, which helps reduce the risk of fraud and enhances transparency

validation-info: Validation that it is an object.
object (RequestPaymentTransaction)

Represents a request to authorize a payment transaction.

validation-info: Validates that the `amount` is present if `request_payment_transaction` is provided.
object (PaymentRequestAuthorizeStepUpConfiguration)

Configuration properties for enabling the customer-present step-up flow

validation-info: Validation that customer_interaction_methods is provided
Responses
200

The authorization result.

Inspect payment_transaction_response.result to see the outcome. If any of the results is STEP_UP_REQUIRED, a payment_request is created which allows the customer to approve.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

403

Forbidden, insufficient privileges to perform the requested operation on the resource.

404

Not Found, the requested resource was not found.

409

Conflict, there was a conflict in using the resource. Idempotency violation or concurrent updates to a resource occurred.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

503

Service Temporarily Unavailable, the system is temporarily unavailable to process the request.

Callbacks
postWebhook callback
post/v2/accounts/{partner_account_id}/payment/authorize
Request samples
application/json

Minimal payment authorization of a previously created payment request.

{
  • "currency": "USD",
  • "request_payment_transaction": {
    }
}
Response samples
application/json

Shows an approved payment authorization response

{
  • "payment_transaction_response": {
    }
}
Callback payload samples
POST: Webhook callback
application/json

The payment request has been submitted to Klarna.

{
  • "metadata": {
    },
  • "payload": {
    }
}

Payment Request API

The Payment Request API allows you to create and manage payment requests for one-off purchases.

Create a server-to-server payment request

Create a server-to-server payment request.

The payment request will have the state SUBMITTED.

SLO Category: The SLO Service Category. Operations that handle all aspects of a Payment Request, including creation, retrieval, updates, and deletion.Payment Request
SLA Service Class: The SLA Service Class this operation is classified at when evaluating SLA compliance. Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
Lifecycle Stage: The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
Availability in Test environment: Indicates if the feature is available in the Klarna Test environment Feature is available in the Klarna Test environmentAvailable
Availability in Production environment: Indicates if the feature is available in the Klarna Production environment Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only

Securityklarna_api_key and klarna_partner_account
Request
path Parameters
partner_account_id
required
string (AccountIdentifier)

Identifier of the Account the action is done on behalf of

Example: krn:partner:global:account:live:LWT2XJSE
query Parameters
include
Array of strings (PaymentRequestInclude)

A comma-separated list of sub-resources to include in the response.

  • headless_interaction - Refers to the Headless Interaction state which is created when HEADLESS customer interaction method is selected
Items Value: "headless_interaction"
header Parameters
Klarna-Interoperability-Token
string (InteroperabilityToken)

The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wcGluZ19zZXNzaW9uX2lkIjoia3JuOnNob3BwaW5nOmV1MTpzZXNzaW9uOjBlOTIyN2MwLTBjNDAtNDdkZi04YzEwLTQwMTRmYzFiZDJiZCIsInN0YXR1cyI6IlBBWU1FTlRfUFJFUEFSRUQiLCJ2ZXJzaW9uIjoxLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0wMVQxMjowMDowMFoiLCJ1cGRhdGVkX2F0IjoiMjAyNC0wMS0wMVQxMjowMDowMFoifQ.1y87kuEKnETy_UCHbTMXx1p4mViZE816okcVmfHFZoo
required
object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]
Request Body schema: application/json
required
currency
required
string (Currency) ^[A-Za-z]{3}$

Currency in ISO 4217 format.

validation-info: There is validation that the provided value is a valid currency. There is no validation that the we have pricing for the given currency.
amount
integer <int64> (PaymentAmount) [ 1 .. 2147483647 ]

Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions.

Invariant: amount = sum(line_items[].total_line_amount)

validation-info: Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
payment_request_reference
string (PaymentRequestReference) [ 1 .. 255 ] characters

Reference to the payment session or equivalent resource created on your side. This will be exposed in payment request webhooks (payment.request.*) for the purpose of correlating your resource with the Klarna Payment Request.

validation-info: Validation for the length
interoperability_data
string <serialized-json> (InteroperabilityData) [ 1 .. 10240 ] characters

This field should be used for any additional interoperability data sent by your Integrating Partner.

validation-info: Field interoperability_data must be between 1 and 10240 characters in length (inclusive)
object (SupplementaryPurchaseData)

Additional information that provide more detailed information about the transaction, which helps reduce the risk of fraud and enhances transparency

validation-info: Validation that it is an object.
Array of objects = 1 items

Payment initiation methods that describes how to launch the purchase flow.

validation-info: Validation that ensures that the array has a min and max size of 1.
payment_option_id
string (PaymentOptionId) [ 1 .. 255 ] characters

Specifies a payment option to be pre-selected in the purchase flow.

The available payment_option_id can be obtained from the Payment Options API.

validation-info: Field must be between 1 and 255 characters in length (inclusive)
Responses
201

Payment request created

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

503

Service Temporarily Unavailable, the system is temporarily unavailable to process the request.

Callbacks
postWebhook callback
post/v2/accounts/{partner_account_id}/payment/requests
Request samples
application/json

Minimum payment request for a 10 USD purchase

{}
Response samples
application/json
{}
Callback payload samples
POST: Webhook callback
application/json

The payment request has been submitted to Klarna.

{
  • "metadata": {
    },
  • "payload": {
    }
}

Read the state of a Payment Request

Allows you to read the state of a payment request.

SLO Category: The SLO Service Category. Operations that handle all aspects of a Payment Request, including creation, retrieval, updates, and deletion.Payment Request
SLA Service Class: The SLA Service Class this operation is classified at when evaluating SLA compliance. Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
Lifecycle Stage: The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
Availability in Test environment: Indicates if the feature is available in the Klarna Test environment Feature is available in the Klarna Test environmentAvailable
Availability in Production environment: Indicates if the feature is available in the Klarna Production environment Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only

Securityklarna_api_key and klarna_partner_account
Request
path Parameters
partner_account_id
required
string (AccountIdentifier)

Identifier of the Account the action is done on behalf of

Example: krn:partner:global:account:live:LWT2XJSE
payment_request_id
required
string (PaymentRequestId) <= 255 characters

The Payment Request ID to read

Example: krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4
query Parameters
include
Array of strings (PaymentRequestInclude)

A comma-separated list of sub-resources to include in the response.

  • headless_interaction - Refers to the Headless Interaction state which is created when HEADLESS customer interaction method is selected
Items Value: "headless_interaction"
header Parameters
required
object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]
Responses
200

Payment request object

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

503

Service Temporarily Unavailable, the system is temporarily unavailable to process the request.

get/v2/accounts/{partner_account_id}/payment/requests/{payment_request_id}
Request samples 
Response samples 
application/json
{}
Update a Payment Request
Allows you to update a payment request that is in the state SUBMITTED.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that handle all aspects of a Payment Request, including creation, retrieval, updates, and deletion.Payment Request
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_request_id
required
string (PaymentRequestId)   <= 255 characters 
The Payment Request ID to update


 
 Example:  krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
required
currency
required
string (Currency) ^[A-Za-z]{3}$
Currency in ISO 4217 format.


 
validation-info:  There is validation that the provided value is a valid currency. There is no validation that the we have pricing for the given currency.
amount
integer <int64>  (PaymentAmount)   [ 1 .. 2147483647 ] 
Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.
This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions.


Invariant: amount = sum(line_items[].total_line_amount)


 
validation-info:  Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
payment_request_reference
string (PaymentRequestReference)   [ 1 .. 255 ] characters 
Reference to the payment session or equivalent resource created on your side.
This will be exposed in payment request webhooks (payment.request.*) for the purpose of correlating your resource with the Klarna Payment Request.


 
validation-info:  Validation for the length
interoperability_data
string <serialized-json>  (InteroperabilityData)   [ 1 .. 10240 ] characters 
This field should be used for any additional interoperability data sent by your Integrating Partner.


 
validation-info:  Field interoperability_data must be between 1 and 10240 characters in length (inclusive)
object (SupplementaryPurchaseData) 
Additional information that provide more detailed information about the transaction, which helps reduce the risk of fraud and enhances transparency


 
validation-info:  Validation that it is an object.
payment_option_id
string (PaymentOptionId)   [ 1 .. 255 ] characters 
Specifies a payment option to be pre-selected in the purchase flow.


The available payment_option_id can be obtained from the Payment Options API.


 
validation-info:  Field must be between 1 and 255 characters in length (inclusive)
Responses 
200
Payment Request updated


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


409
Conflict, there was a conflict in using the resource.
Idempotency violation or concurrent updates to a resource occurred.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


patch/v2/accounts/{partner_account_id}/payment/requests/{payment_request_id}
Request samples 
application/json
{
  • "currency": "USD",
  • "amount": 2000,
  • "payment_request_reference": "partner-payment-reference-12345",
  • "interoperability_data": "string",
  • "supplementary_purchase_data": {
    },
  • "payment_option_id": "string"
}
Response samples 
application/json
{}
Cancel payment request
Allows you to cancel a payment request.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that handle all aspects of a Payment Request, including creation, retrieval, updates, and deletion.Payment Request
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_request_id
required
string (PaymentRequestId)   <= 255 characters 
The Payment Request ID to cancel


 
 Example:  krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment request object


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


409
Conflict, there was a conflict in using the resource.
Idempotency violation or concurrent updates to a resource occurred.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


delete/v2/accounts/{partner_account_id}/payment/requests/{payment_request_id}
Request samples 
Response samples 
application/json
Shows a canceled payment request.


{
  • "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
  • "state": "CANCELED",
  • "state_reason": "PARTNER_CANCELED",
  • "currency": "USD",
  • "amount": 1000,
  • "state_context": { },
  • "expires_at": "2024-01-02T13:00:00Z",
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T13:00:00Z",
  • "customer_interaction_methods": []
}
Payment Dispute API
The Payment Dispute API allows you to create and manage payment disputes.


List Disputes
Retrieve a list of Disputes, segregated by a variety of filter parameters

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that enable access to all dispute-related functionalities, including retrieval, updates, and resolution.Disputes
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are outside the scope of both Transaction Critical and Transaction Non-critical OperationsAdditional Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
query Parameters
payment_product_instance_id
Array of strings
Product Instance IDs to filter by


 
 Example:  payment_product_instance_id=krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918
payment_transaction_id
Array of strings (PaymentTransactionId) 
Payment Transaction IDs to filter by


 
 Example:  payment_transaction_id=krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
Array of strings (PaymentDisputeState) 
States of disputes to filter by


 
reason
Array of strings (PaymentDisputeReason) 
Dispute reason to filter by


Items Enum: "RETURN_NOT_REFUNDED" "PRODUCTS_NOT_RECEIVED" "PRODUCTS_FAULTY" "CAPTURE_AMOUNT_INCORRECT" "PURCHASE_CANCELED" "PURCHASE_UNAUTHORIZED" "PURCHASE_HIGH_RISK"  
 Example:  reason=PRODUCTS_NOT_RECEIVED
sort_by
Array of strings
 Default:  ["opened_at"]
Specifies in which order to sort the results. Then results are ordered in ascending order if not prefixed by a - which orders by descending order.


Items Enum: "deadline_expires_at" "-deadline_expires_at" "opened_at" "-opened_at"  
purchase_references
Array of strings (PurchaseReference) 
Merchant References to filter by


 
 Example:  purchase_references=merchant-order-9876
opened_at_start
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute open dates. Only disputes created after (including) the supplied value will be returned.


 
 Example:  opened_at_start=2024-01-01T12:00:00Z
opened_at_end
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute open dates. Only disputes created before (excluding) the supplied value will be returned.


 
 Example:  opened_at_end=2024-01-01T12:00:00Z
closed_at_start
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute close dates. Only disputes closed after (including) the supplied value will be returned.


 
 Example:  closed_at_start=2024-01-01T12:00:00Z
closed_at_end
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute close dates. Only disputes closed before (excluding) the supplied value will be returned.


 
 Example:  closed_at_end=2024-01-01T12:00:00Z
size
integer <int32> 
Limits the number of items to be returned. If omitted, the default page size will be used.


 
 Example:  size=20
starting_after
string
A cursor used in pagination, referring to a specific item. The last_item returned from a previous call can be used here. The next page will list items after this item. Cannot be used together with ending_before. If both starting_after and ending_before are omitted, the first page will be returned.


 
 Example:  starting_after=Zpq6F3mDYtwK8
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
A paginated list of authorized disputes


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


get/v2/accounts/{partner_account_id}/payment/disputes
Request samples 
Response samples 
application/json
{
  • "disputes": [
    ],
  • "pagination": {
    }
}
Get Dispute Details
Fetch a fully detailed version of a Dispute, including all the associated requests and responses.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that enable access to all dispute-related functionalities, including retrieval, updates, and resolution.Disputes
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are outside the scope of both Transaction Critical and Transaction Non-critical OperationsAdditional Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_dispute_id
required
string
ID of dispute to fetch


 
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Complete dispute with all requests and responses


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


Callbacks 
postDispute state changed webhook callback
postDispute updated webhook callback
get/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}
Request samples 
Response samples 
application/json
{
  • "payment_dispute_id": "krn:payment:eu1:dispute:faulty-products:266091",
  • "dispute_reason": "PRODUCTS_FAULTY",
  • "state": "ARBITRATION_PENDING",
  • "previous_state": "MERCHANT_EVIDENCE_PENDING",
  • "payment_transaction_id": "krn:payment:eu1:authorization:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
  • "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  • "payment_product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "dispute_details": {
    },
  • "merchant_evidence": [
    ],
  • "config": {
    },
  • "created_at": "2020-04-15T08:31:00Z",
  • "updated_at": "2020-05-09T08:31:00Z",
  • "arbitration_started_at": "2020-05-08T00:00:00Z"
}
Callback payload samples 
application/json
A payment dispute has just been submitted to Klarna.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Accept dispute loss
Accept the loss of a dispute, which will be closed with the chargeback activation

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that enable access to all dispute-related functionalities, including retrieval, updates, and resolution.Disputes
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are outside the scope of both Transaction Critical and Transaction Non-critical OperationsAdditional Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_dispute_id
required
string
ID of dispute to accept loss for


 
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
202
Loss was accepted successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


409
The dispute is not in a state where the loss can be accepted. Read the error details for further information.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/accept-loss
Request samples 
Response samples 
application/json
{
  • "error_id": "5a3f6b9c-9b3b-4b7e-8f9d-9b9a4b9a4b9a",
  • "error_type": "INPUT_ERROR",
  • "error_code": "INVALID_CONTENT_TYPE",
  • "error_message": "The received input is not valid JSON.\nUnterminated string at 19 [character 20 line 1].\n"
}
Upload merchant evidence attachment
Uploads merchant attachment to be linked to a dispute response. File size limit is 7MB.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that enable access to all dispute-related functionalities, including retrieval, updates, and resolution.Disputes
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are outside the scope of both Transaction Critical and Transaction Non-critical OperationsAdditional Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_dispute_id
required
string
ID of dispute for which the request to add response to belongs


 
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: multipart/form-data
filename
string
Name of a file to upload


 
validation-info:  Validation that is not null and is a valid string
file
required
string <binary> 
File contents


 
validation-info:  Validation that is not null and is a valid string
Responses 
201
Attachment uploaded successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/attachments
Request samples 
Response samples 
application/json
{
  • "payment_dispute_attachment_id": "krn:payment:eu1:dispute:256947:attachment:3"
}
Respond to merchant evidence request
Respond to merchant evidence request.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that enable access to all dispute-related functionalities, including retrieval, updates, and resolution.Disputes
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are outside the scope of both Transaction Critical and Transaction Non-critical OperationsAdditional Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available for testing purposes only in the Klarna Production environment and should not be use to process real transactionsTest-only
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
Identifier of the Account the action is done on behalf of


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_dispute_id
required
string
ID of dispute for which the request to add response to belongs


 
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
required
Response to add to request


One of:
Merchant response to a dispute where the customer claims that the products were faulty


additional_information
string
Free-text string with additional information about the dispute response


 
Array of objects (PaymentDisputeRespondToEvidenceRequestPayloadAttachment) 
List of evidence provided by the merchant to support the dispute response.


 
required
object
 
Responses 
201
Dispute's evidence request response was submitted successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


409
The dispute is not in a state where a response can be submitted.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/respond
Request samples 
application/json
Responding to an evidence request with request type 'RETURN_NOT_REFUNDED'


{
  • "additional_information": "Additional free text information",
  • "created_at": "2020-05-08T08:32:14Z",
  • "attachments": [
    ],
  • "details": {
    }
}
Response samples 
application/json
{
  • "response_id": "krn:payment:eu1:dispute:266092:request:1:response:1",
  • "created_at": "2020-05-09T09:32:18Z",
  • "additional_information": "Additional free text information",
  • "attachments": [
    ],
  • "details": {
    }
}
Payment Transaction API
The Payment Transaction API allows you to create and manage payment transactions.


Read Payment Transaction
Request to retrieve the details of a payment transaction.
A payment transaction encapsulates crucial details such as the authorized amount, currency, line items and shipping information.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that allow read access to transaction management, e.g. enabling retrieval of payment transaction details.Read-only Payment Transaction
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment Transaction has been successfully retrieved.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment funding state-change
get/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}
Request samples 
Response samples 
application/json
Shows a payment transaction that has been created but not yet acted upon.


{
  • "payment_transaction_id": "krn:payment:us1:transaction:4b8b6350-6b72-42c5-b946-f088adcdc216",
  • "currency": "USD",
  • "amount": 2100,
  • "payment_transaction_reference": "payment-transaction-reference-1234",
  • "payment_funding": {
    },
  • "supplementary_purchase_data": {
    },
  • "payment_captures": [ ],
  • "payment_refunds": [ ],
  • "payment_chargebacks": [ ],
  • "state": "AUTHORIZED",
  • "state_reason": "AUTHORIZED",
  • "created_at": "2024-01-01T13:00:00Z",
  • "expires_at": "2024-01-29T13:00:00Z",
  • "original_authorization_amount": 2100,
  • "remaining_authorization_amount": 2100,
  • "customer_profile": {
    },
  • "settlement_currency": "USD",
  • "payment_pricing": {
    }
}
Callback payload samples 
POST: Webhook: Payment funding state-change
application/json
Shows a payment funding pending webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Update Payment Transaction
Request to update details of a payment transaction.


The update operation should be performed when there is a need to change either the payment_transaction_reference or the purchase_reference. These fields are essential for aligning your internal records with Klarna's transaction records and ensuring accurate tracking and reconciliation.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
object
Supplementary information for the purchase that helps reduce the risk of fraud, enhances transparency, and improves the customer's post-purchase experience.


 
validation-info:  tbd
payment_transaction_reference
string (PaymentTransactionReference)   [ 1 .. 255 ] characters 
Reference to the payment or equivalent resource created on your side.
This will be exposed in the Payment Transaction webhooks for the purpose of correlating your resource with the Klarna Payment Transaction.


 
validation-info:  Validation for the length
Responses 
200
Payment Transaction has been successfully updated.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


patch/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}
Request samples 
application/json
Update purchase reference and payment transaction reference


{
  • "supplementary_purchase_data": {
    },
  • "payment_transaction_reference": "new-payment-transaction-reference-1234"
}
Response samples 
application/json
Shows a payment transaction that has been updated prior to completion.


{
  • "payment_transaction_id": "krn:payment:us1:transaction:4b8b6350-6b72-42c5-b946-f088adcdc216",
  • "payment_transaction_reference": "new-payment-transaction-reference-1234",
  • "amount": 2100,
  • "currency": "USD",
  • "supplementary_purchase_data": {
    },
  • "payment_captures": [ ],
  • "payment_refunds": [ ],
  • "payment_chargebacks": [ ],
  • "state": "AUTHORIZED",
  • "state_reason": "AUTHORIZED",
  • "created_at": "2024-01-01T13:00:00Z",
  • "updated_at": "2024-01-02T13:00:00Z",
  • "expires_at": "2024-01-29T13:00:00Z",
  • "original_authorization_amount": 2100,
  • "remaining_authorization_amount": 2100,
  • "customer_profile": {
    },
  • "payment_funding": {
    },
  • "settlement_currency": "USD",
  • "payment_pricing": {
    }
}
Reauthorize Payment Transaction
Request to reauthorize a payment transaction.


The reauthorize operation is necessary when the amount, line_items, or shipping details are changed.
This ensures that the payment transaction is reauthorized with the up-to-date details and can be completed without any issues.
Note that the reauthorization operation is subject to a second risk assessment and may be rejected.


Additionally, reauthorization should be performed when the existing authorization is close to expiry, and the payment will not be completed within the current authorization period.
This will provide sufficient time to complete the payment transaction without any issues.
Be aware that a payment transaction is deemed to be CLOSED 7 days following the expiry and cannot be reauthorized thereafter.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
amount
integer <int64>  (PaymentAmount)   [ 1 .. 2147483647 ] 
Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.
This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions.


Invariant: amount = sum(line_items[].total_line_amount)


 
validation-info:  Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
object
Supplementary information for the purchase that helps reduce the risk of fraud, enhances transparency, and improves the customer's post-purchase experience.


 
validation-info:  tbd
extension_days
integer <int64>   [ 1 .. 180 ] 
The number of days by which the payment authorization period will be extended. If the transaction is expired, the extension_days are added to the current date. Otherwise, the extension_days are added to the current expires_at date.


The new expiration date is calculated using the formula max(current_date, expires_at) + extension_days.


A payment transaction cannot have an authorization period longer than 360 days, and any attempt to extend beyond that period will be rejected.


Constraint: max(current_date, expires_at) + expiration_days <= created_at + '360 days'


 
validation-info:  tbd
Responses 
200
The reauthorization of the payment transaction has been processed.


Note that this does not indicate successful reauthorization; it may have been rejected. You should check the result field for the final outcome.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction state-change
post/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}/authorize
Request samples 
application/json
Reauthorize payment transaction with new payment amount and line items


{}
Response samples 
application/json
Shows a payment transaction that has been reauthorized and waiting for further actions.


{
  • "result": "AUTHORIZED",
  • "payment_transaction": {
    }
}
Callback payload samples 
POST: Webhook: Payment transaction state-change
application/json
Shows a payment transaction authorized webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Capture Payment Transaction
Request to capture a payment transaction.
The capture should be performed in conjunction with the shipment of the purchased goods.
Upon successful completion, the process of settling the funds with the merchant will commence.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
capture_amount
integer (PaymentCaptureAmount)   [ 0 .. 2147483647 ] 
The amount of the capture including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.
If not specified, a capture for the remaining_authorization_amount will be performed.


Invariant: capture_amount = sum(line_items[].total_amount)


 
validation-info:  tbd
payment_capture_reference
string (PaymentCaptureReference)   [ 1 .. 255 ] characters 
Reference to the capture or equivalent resource created on your side.
This will be exposed in the Payment Transaction webhooks and included in the settlement file.


 
validation-info:  tbd
object (SupplementaryCaptureData) 
Supplementary information for the capture that enhances transparency and improves the customer's post-purchase experience.


 
validation-info:  tbd
Responses 
201
Payment Transaction has been successfully captured.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction state-change
postWebhook: Payment transaction captured
post/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}/capture
Request samples 
application/json
Shows a capture request with capture amount and line items


{}
Response samples 
application/json
Shows a successful payment capture response


{}
Callback payload samples 
application/json
Shows a payment transaction authorized webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Refund Payment Transaction
Request to refund a payment transaction.


The refund should be performed when customers return the purchased items.
Upon successful completion, the process of returning the funds to the customer will commence,
and the merchant's settlement balance will be adjusted accordingly.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
refund_amount
required
integer  [ 0 .. 2147483647 ] 
The amount of the refund including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.


Invariant: refund_amount = sum(line_items[].total_amount)


Constraint: refund_amount <= sum(captures[].capture_amount) - sum(refunds[].refund_amount)


 
validation-info:  tbd
payment_refund_reference
string (PaymentRefundReference)   [ 1 .. 255 ] characters 
Reference to the refund or equivalent resource created on your side.
This will be exposed in the Payment Transaction webhooks and included in the settlement file.


 
validation-info:  Validation for the length
object (SupplementaryRefundData) 
Supplementary information for the refund that enhances transparency and improves the customer's post-purchase experience.


 
validation-info:  tbd
Responses 
201
Payment Transaction has been successfully refunded.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction refunded
post/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}/refund
Request samples 
application/json
Shows a refund request with refund amount and line items


{}
Response samples 
application/json
Shows a successful response to a refund operation on a payment transaction.


{}
Callback payload samples 
POST: Webhook: Payment transaction refunded
application/json
Shows a payment transaction refunded webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Void Payment Transaction
Request to void a payment transaction.


The void operation should be performed when the payment is no longer intended to be fulfilled.
Upon successful completion, any remaining authorization will subsequently be released.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment Transaction has been successfully voided.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction state-change
post/v2/accounts/{partner_account_id}/payment/transactions/{payment_transaction_id}/void
Request samples 
Response samples 
application/json
Shows a payment transaction that has been partially captured and completed upon a void operation. Any remaining authorization has been released.


{
  • "payment_transaction_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162",
  • "payment_transaction_reference": "payment-transaction-reference-1234",
  • "amount": 15000,
  • "currency": "EUR",
  • "payment_funding": {
    },
  • "supplementary_purchase_data": {},
  • "payment_captures": [],
  • "payment_refunds": [ ],
  • "payment_chargebacks": [ ],
  • "state": "COMPLETED",
  • "state_reason": "VOIDED",
  • "previous_state": "AUTHORIZED",
  • "created_at": "2024-01-01T13:00:00Z",
  • "updated_at": "2024-01-02T13:00:00Z",
  • "expires_at": "2024-01-29T13:00:00Z",
  • "original_authorization_amount": 15000,
  • "remaining_authorization_amount": 0,
  • "customer_profile": {
    },
  • "settlement_currency": "USD",
  • "payment_pricing": {
    }
}
Callback payload samples 
POST: Webhook: Payment transaction state-change
application/json
Shows a payment transaction authorized webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Read Payment Capture
Request to retrieve the details of a payment capture.
A payment capture encapsulates crucial details such as the capture amount, line items and shipment details.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that allow read access to transaction management, e.g. enabling retrieval of payment transaction details.Read-only Payment Transaction
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_capture_id
required
string (PaymentCaptureId)   <= 255 characters 
The unique identifier of the payment capture.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:capture:1
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment Capture has been successfully retrieved.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


get/v2/accounts/{partner_account_id}/payment/captures/{payment_capture_id}
Request samples 
Response samples 
application/json
Shows a successful payment capture response


{}
Refund Payment Capture
Request to refund a payment capture.


The refund should be performed when customers return the purchased items.
Upon successful completion, the process of returning the funds to the customer will commence,
and the merchant's settlement balance will be adjusted accordingly.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_capture_id
required
string (PaymentCaptureId)   <= 255 characters 
The unique identifier of the payment capture.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:capture:1
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
refund_amount
required
integer  [ 0 .. 2147483647 ] 
The amount of the refund including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500.


Invariant: refund_amount = sum(line_items[].total_amount)


Constraint: refund_amount <= sum(captures[payment_capture_id].capture_amount) - sum(refunds[payment_capture_id].refund_amount)


 
validation-info:  tbd
payment_refund_reference
string (PaymentRefundReference)   [ 1 .. 255 ] characters 
Reference to the refund or equivalent resource created on your side.
This will be exposed in the Payment Transaction webhooks and included in the settlement file.


 
validation-info:  Validation for the length
object (SupplementaryRefundData) 
Supplementary information for the refund that enhances transparency and improves the customer's post-purchase experience.


 
validation-info:  tbd
Responses 
201
Payment Capture has been successfully refunded.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction refunded
post/v2/accounts/{partner_account_id}/payment/captures/{payment_capture_id}/refund
Request samples 
application/json
Shows a refund request with refund amount and line items


{}
Response samples 
application/json
Shows a successful response to a refund operation on a payment capture.


{
  • "payment_refund_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:refund:1",
  • "payment_capture_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:capture:1",
  • "payment_refund_reference": "refund-reference-123",
  • "refund_amount": 5000,
  • "refunded_at": "2024-01-02T13:00:00Z",
  • "supplementary_refund_data": {}
}
Callback payload samples 
POST: Webhook: Payment transaction refunded
application/json
Shows a payment transaction refunded webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Read Payment Refund
Request to retrieve the details of a payment refund.
A payment refund encapsulates crucial details such as the refund amount and line items.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that allow read access to transaction management, e.g. enabling retrieval of payment transaction details.Read-only Payment Transaction
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_refund_id
required
string (PaymentRefundId)   <= 255 characters 
The unique identifier of the payment refund.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:refund:1
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment refund has been successfully retrieved.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


get/v2/accounts/{partner_account_id}/payment/refunds/{payment_refund_id}
Request samples 
Response samples 
application/json
Shows a successful response to a refund operation on a payment transaction.


{}
Read Payment Chargeback
Request to retrieve the details of a payment chargeback.
A payment chargeback encapsulates crucial details such as the chargeback amount and chargeback reason.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that allow read access to transaction management, e.g. enabling retrieval of payment transaction details.Read-only Payment Transaction
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is available in the Klarna Test environmentAvailable
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is available in the Klarna Production environmentAvailable
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
partner_account_id
required
string (AccountIdentifier) 
The unique identifier of the account for which the action is performed.


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_chargeback_id
required
string (PaymentChargebackId)   <= 255 characters 
The unique identifier of the payment chargeback.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:chargeback:1
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Responses 
200
Payment chargeback has been successfully retrieved.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


Callbacks 
postWebhook: Payment transaction chargeback
get/v2/accounts/{partner_account_id}/payment/chargebacks/{payment_chargeback_id}
Request samples 
Response samples 
application/json
Shows a payment chargeback created as a result of dispute merchant loss.


{
  • "payment_dispute_id": "krn:payment:eu1:transaction:f9669608-a24d-43ef-9f34-ec3d785dc1ae:dispute:1",
  • "payment_chargeback_id": "krn:payment:eu1:transaction:f9669608-a24d-43ef-9f34-ec3d785dc1ae:chargeback:1",
  • "chargeback_amount": 5000,
  • "chargeback_reason": "DISPUTE_ARBITRATION_LOST",
  • "chargeback_at": "2024-01-02T13:00:00Z",
  • "line_items": []
}
Callback payload samples 
POST: Webhook: Payment transaction chargeback
application/json
Shows a payment transaction chargeback webhook.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Card Settlements API
Create a card settlement for a payment transaction.
Request to create a card settlement for a payment transaction.


Upon successful completion, the card settlement is created and all the card info are returned to the caller.


The payment_transaction_id input body parameter acts as the idempotency key of the request.
If multiple requests are made with the same payment_transaction_id, only the first request will be processed and the subsequent requests will return the same card settlement.

              

                
                    SLO Category:
                    The SLO Service Category.
                
                 Operations that support the creation and modification of payment transactions, including submission and updates.Payment Transaction General
              

              

                
                    SLA Service Class:
                    The SLA Service Class this operation is classified at when evaluating SLA compliance.
                
                 Operations, webhooks and other services that are essential for a Partner to process payments with KlarnaTransactions Critical Services
              

              

                
                     Lifecycle Stage:
                    The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage
                
                 Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release
              

              

                
                    Availability in Test environment:
                    Indicates if the feature is available in the Klarna Test environment
                
                 Feature is not available in the Klarna Test environmentNot available
              

              

                
                    Availability in Production environment:
                    Indicates if the feature is available in the Klarna Production environment
                
                 Feature is not available in the Klarna Production environmentNot available
              


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
payment_transaction_id
required
string (PaymentTransactionId)   <= 255 characters 
The unique identifier of the payment transaction.


 
 Example:  krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0
validation-info:  Validation for the length
header Parameters
required
object
Metadata about the integrator and originators of the request in n object, serialized as a valid JSON


 
 Example:  object=[object Object]
Request Body schema: application/json
card_settlement_reference
string (CardSettlementReference)   [ 1 .. 255 ] characters 
Reference to the card settlement or equivalent resource created on your side.


 
validation-info:  Validation for the length
Responses 
201
Card Settlement was created successfully.


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


503
Service Temporarily Unavailable, the system is temporarily unavailable to process the request.


post/v2/accounts/{account_id}/payment/transactions/{payment_transaction_id}/card-settlements
Request samples 
application/json
Valid Card Settlement creation payload.


{
  • "card_settlement_reference": "partner-card-settlement-12345"
}
Response samples 
application/json
Card Settlement creation response.


{
  • "card_settlement_id": "krn:partner:us1:payment:card-settlement:5cd46f7e-573d-4b02-bab8-1f1c0e343291",
  • "card_settlement_reference": "partner-card-settlement-12345",
  • "payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
  • "card": {
    }
}
Cookies
Terms of Service
© Klarna 2024