API & SDKsSupport

Klarna Partner Product API - Payment (v1/r5)

Download OpenAPI specification:Download

URL: https://www.klarna.com

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

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.

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

Identifier of the Account the action is done on behalf of

Example: krn:partner:global:account:live:LWT2XJSE
header Parameters
X-Klarna-Client-Id
string (PaymentRequestClientId) [ 1 .. 255 ] characters

Used to identify that the request is linked to a specific client with a specific configuration.

X-Klarna-Customer-Token
string (CustomerToken) <= 1024 characters

The customer_token represents the tokenized customer and allows you to act on behalf of the customer.

Example: krn:partner:us1:live:identity:customer-token:vVQGmYzlfsQ16dko3jcwY5lV8hBgKs9a
Request Body schema: application/json
required
Any of:

Payment request for a one-off purchase

currency
required
string (Currency) ^[A-Za-z]{3}$

Currency in ISO 4217 format.

Supported currencies:

  • AUD
  • EUR
  • CAD
  • CZK
  • DKK
  • HUF
  • MXN
  • NZD
  • NOK
  • PLN
  • RON
  • SEK
  • CHF
  • GBP
  • USD
payment_amount
required
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: payment_amount = sum(line_items[].total_line_amount)

payment_reference
string (PaymentReference) [ 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.

merchant_reference
string (MerchantReference) [ 1 .. 256 ] characters

Used for storing the customer-facing order number. It will be displayed to customers on the Klarna app and other communications. It will also be included in settlement reports for the purpose of reconciliation. If you are a direct merchant with Klarna, this can be the same as payment_transaction_reference. If you are a PSP, this is the reference your merchant generated for their customer order.

Array of objects (PaymentRequestLineItems)

Detailed line item information of the purchase. This data is used for fraud detection and customer communication.

Array of objects (PaymentRequestShipping)

Shipping information for the purchase. This data is used for fraud detection and customer communication.

If the purchase contains multiple shipments with different recipients, you must provide one shipping object per shipment.

object (PaymentRequestCustomer)

This represents who the customer is according to the merchant. These data points may be used by Klarna to simplify sign-up and during fraud assessment, they will not be used for underwriting and will not be persisted on created Payment Transactions.

The details of the customer and the Klarna Customer Account paying for the purchase will be returned after a successful payment request transaction, and may be different from the details in this object.

object (SupplementaryPurchaseData)

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

required
object

Configuration of the payment request

object

Interoperability configurations for the payment request

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.

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/v1/accounts/{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.

Securityklarna_api_key and klarna_partner_account
Request
path Parameters
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
Responses
200

Payment request object

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/v1/accounts/{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.


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
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
X-Klarna-Client-Id
string (PaymentRequestClientId)   [ 1 .. 255 ] characters 
Used to identify that the request is linked to a specific client with a specific configuration.


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


Supported currencies:


    

  • AUD
    • 

  • EUR
    • 

  • CAD
    • 

  • CZK
    • 

  • DKK
    • 

  • HUF
    • 

  • MXN
    • 

  • NZD
    • 

  • NOK
    • 

  • PLN
    • 

  • RON
    • 

  • SEK
    • 

  • CHF
    • 

  • GBP
    • 

  • USD
    • 



 
payment_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: payment_amount = sum(line_items[].total_line_amount)


 
payment_reference
string (PaymentReference)   [ 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.


 
merchant_reference
string (MerchantReference)   [ 1 .. 256 ] characters 
Used for storing the customer-facing order number. It will be displayed to customers on the Klarna app and other communications. It will also be included in settlement reports for the purpose of reconciliation.
If you are a direct merchant with Klarna, this can be the same as payment_transaction_reference. If you are a PSP, this is the reference your merchant generated for their customer order.


 
Array of objects (PaymentRequestLineItems) 
Detailed line item information of the purchase.
This data is used for fraud detection and customer communication.


 
Array of objects (PaymentRequestShipping) 
Shipping information for the purchase. This data is used for fraud detection and customer communication.


If the purchase contains multiple shipments with different recipients, you must provide one shipping object per shipment.


 
object (PaymentRequestCustomer) 
This represents who the customer is according to the merchant.
These data points may be used by Klarna to simplify sign-up and during fraud assessment, they will not be used for underwriting and will not be persisted on created Payment Transactions.


The details of the customer and the Klarna Customer Account paying for the purchase will be returned after a successful payment request transaction, and may be different from the details in this object.


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


 
object (PaymentRequestConfiguration) 
Configuration of the payment request


 
object (PaymentRequestInteroperability) 
Interoperability configurations for the payment request


 
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/v1/accounts/{account_id}/payment/requests/{payment_request_id}
Request samples 
application/json
{
  • "currency": "USD",
  • "payment_amount": 2000,
  • "payment_reference": "partner-payment-reference-12345",
  • "merchant_reference": "merchant-order-9876",
  • "line_items": [],
  • "shipping": [
    ],
  • "customer": {
    },
  • "supplementary_purchase_data": {
    },
  • "config": {},
  • "interoperability": {
    }
}
Response samples 
application/json
{}
Cancel payment request
Allows you to cancel a payment request.


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
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
Responses 
200
Payment request object


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/v1/accounts/{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",
  • "state_context": { },
  • "state_expires_at": "2024-01-01T15:00:00Z",
  • "expires_at": "2024-01-02T13:00:00Z",
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T13:00:00Z",
  • "payment_request": {}
}
Confirm a Payment Request using a confirmation token
To confirm a payment request you must provide the payment confirmation token returned after a successful payment flow.


This endpoint is idempotent and can be called multiple times with the same confirmation token, the same response will be returned.


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


 
 Example:  krn:partner:global:account:live:LWT2XJSE
payment_confirmation_token
required
string (PaymentConfirmationToken)   <= 255 characters 
The payment confirmation token of the Payment Request to confirm


 
 Example:  krn:payment:eu1:confirmation-token:e15432a5-ebcc-45bc-944c-e61399db597b
Request Body schema: application/json
required
Any of:
Confirmation of a one-off purchase, with optional token sign up


currency
required
string^[A-Za-z]{3}$
Currency of the payment amount in 3-letter ISO 4217 currency code.
Must be identical to the value in the payment request creation.


 
payment_amount
required
integer <int64>   [ 1 .. 2147483647 ] 
Total payment amount that you want to charge the customer.


Must be identical to the value in the payment request creation.


 
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.


 
Array of objects (Shipping) 
Confirmation of shipping details if not collected by Klarna.
If the details passed here do not match the details passed in the payment request the confirmation will be rejected.


 
object (PaymentRequestConfirmConfiguration) 
Configuration properties for the payment request confirmation


 
Responses 
200
Payment request authorized


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.


Callbacks 
postWebhook callback
post/v1/accounts/{account_id}/payment/confirmation-tokens/{payment_confirmation_token}/confirm
Request samples 
application/json
{
  • "currency": "USD",
  • "payment_amount": 2000,
  • "payment_transaction_reference": "partner-transaction-reference-4567",
  • "shipping": [
    ],
  • "config": {
    }
}
Response samples 
application/json
Shows an authorized payment request


{
  • "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
  • "state": "AUTHORIZED",
  • "state_expires_at": "2024-01-01T15:00:00Z",
  • "state_context": {
    },
  • "expires_at": "2024-01-02T13:00:00Z",
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T13:00:00Z",
  • "payment_request": {}
}
Callback payload samples 
POST: Webhook callback
application/json
The payment request has been confirmed and the payment is authorized.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Payment Token API
Charge a tokenized customer for a subscription or on-demand usage.
Charge a tokenized customer for a subscription or on-demand usage.


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


 
 Example:  krn:partner:global:account:live:LWT2XJSE
header Parameters
X-Klarna-Client-Id
string (PaymentRequestClientId)   [ 1 .. 255 ] characters 
Used to identify that the request is linked to a specific client with a specific configuration.


 
X-Klarna-Customer-Token
required
string (CustomerToken)   <= 1024 characters 
The customer token of the account linked customer you wish to charge.


 
 Example:  krn:partner:us1:live:identity:customer-token:vVQGmYzlfsQ16dko3jcwY5lV8hBgKs9a
Request Body schema: application/json
required
currency
required
string (Currency) ^[A-Za-z]{3}$
Currency in ISO 4217 format.


Supported currencies:


    

  • AUD
    • 

  • EUR
    • 

  • CAD
    • 

  • CZK
    • 

  • DKK
    • 

  • HUF
    • 

  • MXN
    • 

  • NZD
    • 

  • NOK
    • 

  • PLN
    • 

  • RON
    • 

  • SEK
    • 

  • CHF
    • 

  • GBP
    • 

  • USD
    • 



 
payment_amount
required
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: payment_amount = sum(line_items[].total_line_amount)


 
payment_reference
string (PaymentReference)   [ 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.


 
merchant_reference
string (MerchantReference)   [ 1 .. 256 ] characters 
Used for storing the customer-facing order number. It will be displayed to customers on the Klarna app and other communications. It will also be included in settlement reports for the purpose of reconciliation.
If you are a direct merchant with Klarna, this can be the same as payment_transaction_reference. If you are a PSP, this is the reference your merchant generated for their customer order.


 
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.


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


 
Array of objects (PaymentRequestLineItems) 
Detailed line item information of the purchase.
This data is used for fraud detection and customer communication.


 
Array of objects (PaymentRequestShipping) 
Shipping information for the purchase. This data is used for fraud detection and customer communication.


If the purchase contains multiple shipments with different recipients, you must provide one shipping object per shipment.


 
object (PaymentRequestCustomer) 
This represents who the customer is according to the merchant.
These data points may be used by Klarna to simplify sign-up and during fraud assessment, they will not be used for underwriting and will not be persisted on created Payment Transactions.


The details of the customer and the Klarna Customer Account paying for the purchase will be returned after a successful payment request transaction, and may be different from the details in this object.


 
required
object (PaymentRequestChargeConfiguration) 
Configuration properties for the token charge request


 
Responses 
201
The token charge can result in one of the following outcomes:


    

  • Successful Authorization (state: AUTHORIZED): The charge was approved, and the response body includes the Payment Transaction ID.
    • 

  • Declined (state: DECLINED): The charge was declined. The response body includes a state_reason for the decline.
    • 

  • Step-Up Flow Activation (state: SUBMITTED): The charge was declined, and a step-up authentication flow has been activated. The response body includes the state_context, which provides the distribution URL where the customer must be redirected for payment authorization.
When handling the response, examine the state field to determine the appropriate next steps.
    • 



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/v1/accounts/{account_id}/payment/token/charge
Request samples 
application/json
Charge a customer for a previously created subscription for a customer that is not present. The customer_token is passed in the header X-Klarna-Customer-Token.


{
  • "currency": "USD",
  • "payment_amount": 999,
  • "payment_reference": "partner-payref-1234",
  • "merchant_reference": "order-5678",
  • "supplementary_purchase_data": {
    },
  • "config": {
    }
}
Response samples 
application/json
Shows a successful token charge response


{
  • "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
  • "state": "AUTHORIZED",
  • "state_expires_at": "2024-01-01T15:00:00Z",
  • "state_context": {
    },
  • "expires_at": "2024-01-02T13:00:00Z",
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T13:00:00Z",
  • "payment_request": {}
}
Callback payload samples 
POST: Webhook callback
application/json
The payment request has been submitted to Klarna.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Payment Transaction API
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.


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


 
 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
Responses 
200
Payment Transaction has been successfully retrieved.


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/v1/accounts/{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",
  • "payment_amount": 2100,
  • "acquiring_channel": "ECOMMERCE",
  • "merchant_reference": "merchant-order-reference-5678",
  • "payment_transaction_reference": "payment-transaction-reference-1234",
  • "line_items": [],
  • "shipping": [
    ],
  • "captures": [ ],
  • "refunds": [ ],
  • "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,
  • "payment_pricing": {
    }
}
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 merchant_reference. These fields are essential for aligning your internal records with Klarna's transaction records and ensuring accurate tracking and reconciliation.


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


 
 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
Request Body schema: application/json
merchant_reference
string (MerchantReference)   [ 1 .. 256 ] characters 
Used for storing the customer-facing order number. It will be displayed to customers on the Klarna app and other communications. It will also be included in settlement reports for the purpose of reconciliation.
If you are a direct merchant with Klarna, this can be the same as payment_transaction_reference. If you are a PSP, this is the reference your merchant generated for their customer order.


 
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.


 
Responses 
200
Payment Transaction has been successfully updated.


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/v1/accounts/{account_id}/payment/transactions/{payment_transaction_id}
Request samples 
application/json
Update merchant reference and payment transaction reference


{
  • "merchant_reference": "new-merchant-order-reference-5678",
  • "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",
  • "currency": "USD",
  • "payment_amount": 2100,
  • "acquiring_channel": "ECOMMERCE",
  • "merchant_reference": "new-merchant-order-reference-5678",
  • "payment_transaction_reference": "new-payment-transaction-reference-1234",
  • "line_items": [],
  • "shipping": [
    ],
  • "captures": [ ],
  • "refunds": [ ],
  • "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,
  • "payment_pricing": {
    }
}
Reauthorize Payment Transaction
Request to reauthorize a payment transaction.


The reauthorize operation is necessary when the payment_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.


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
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
Request Body schema: application/json
payment_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: payment_amount = sum(line_items[].total_line_amount)


 
Array of objects (PaymentTransactionLineItems) 
Detailed line item information of the purchase.
This data is used for fraud detection and customer communication.


 
Array of objects (PaymentTransactionShipping) 
Shipping information for the purchase. This data is used for fraud detection and customer communication.


If the purchase contains multiple shipments with different recipients, you must provide one shipping object per shipment.


 
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'


 
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.


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/v1/accounts/{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": {
    }
}
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.


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


 
 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
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)


 
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.


 
Array of objects (PaymentCaptureLineItems) 
Detailed line item information of the capture.
This data is used for customer communication.


 
Array of objects (Shipments) 
Detailed shipment information.
This data is used for customer communication.


 
Responses 
201
Payment Transaction has been successfully captured.


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/v1/accounts/{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


{}
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.


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


 
 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
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)


 
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.


 
Array of objects (PaymentRefundLineItems) 
Detailed line item information of the refund.
This data is used for customer communication.


 
Responses 
201
Payment Transaction has been successfully refunded.


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/v1/accounts/{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.


{}
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.


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


 
 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
Responses 
200
Payment Transaction has been successfully voided.


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/v1/accounts/{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",
  • "currency": "EUR",
  • "payment_amount": 15000,
  • "acquiring_channel": "ECOMMERCE",
  • "merchant_reference": "merchant-order-reference-5678",
  • "payment_transaction_reference": "payment-transaction-reference-1234",
  • "line_items": [],
  • "shipping": [
    ],
  • "captures": [],
  • "refunds": [ ],
  • "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,
  • "payment_pricing": {
    }
}
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.


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


 
 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
Responses 
200
Payment Capture has been successfully retrieved.


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/v1/accounts/{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.


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


 
 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
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)


 
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.


 
Array of objects (PaymentRefundLineItems) 
Detailed line item information of the refund.
This data is used for customer communication.


 
Responses 
201
Payment Capture has been successfully refunded.


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/v1/accounts/{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.


{}
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.


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


 
 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
Responses 
200
Payment refund has been successfully retrieved.


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/v1/accounts/{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.


Securityklarna_api_key and klarna_partner_account 
Request 
path Parameters
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
Responses 
200
Payment chargeback has been successfully retrieved.


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/v1/accounts/{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": []
}
Cookies
Terms of Service
© Klarna 2024