Klarna Partner Product API - Payment (release/4)

Download OpenAPI specification:Download

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

Authentication

klarna_api_key

Use the Klarna API key as HTTP Basic Authentication credentials

Security Scheme Type	API Key
Header parameter name:	Authorization

klarna_partner_account

Klarna Partner Account ID when acting on-behalf of another account

Security Scheme Type	API Key
Header parameter name:	Klarna-Partner-Account

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.

Request

Security:

klarna_api_keyklarna_partner_account

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.

Request Body schema: application/json

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

Payload
curl
JavaScript
Node.js

application/json

Minimum payment request for a 10 USD purchase

{"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}

Response samples

application/json

{"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED",
"state_expires_at": "2024-01-01T15:00:00Z",
"state_context": {"distribution": {"url": "https://pay.klarna.com/l/ZjW2Xipgh0tjbrBGD7hzJM"
}
},
"expires_at": "2024-01-02T13:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T13:00:00Z",
"payment_request": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Callback payload samples

POST: Webhook callback

application/json

The payment request has been submitted to Klarna.

{"metadata": {"event_type": "payment.request.state-change.submitted",
"event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
"event_version": "v1",
"occurred_at": "2024-01-01T12:00:00Z",
"account_id": "krn:partner:account:206bbb83-9b6e-46fa-940d-337153c04a58",
"product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
"webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
"live": true
},
"payload": {"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_reference": "partner-payref-1234",
"merchant_reference": "order-5678",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED"
}
}

Read the state of a Payment Request

Allows you to read the state of a payment request.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/requests/{payment_request_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

Response samples

application/json

{"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED",
"state_expires_at": "2024-01-01T15:00:00Z",
"state_context": {"distribution": {"url": "https://pay.klarna.com/l/ZjW2Xipgh0tjbrBGD7hzJM"
}
},
"expires_at": "2024-01-02T13:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T13:00:00Z",
"payment_request": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Update a Payment Request

Allows you to update a payment request that is in the state SUBMITTED.

Request

Security:

klarna_api_keyklarna_partner_account

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

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

Payload
curl
JavaScript
Node.js

application/json

{"currency": "USD",
"payment_amount": 2000,
"payment_reference": "partner-payment-reference-12345",
"merchant_reference": "merchant-order-9876",
"line_items": [{"name": "Black fountain pen",
"quantity": 2,
"total_amount": 2000,
"total_tax_amount": 0,
"unit_price": 1000,
"product_url": "https://merchant.example/product/pencil-3270220049012.html",
"image_url": "https://merchant.example/images/pencil-3270220049012.png",
"product_identifier": "3270220049012",
"reference": "cart-item-1234",
"shipping_reference": "shipping-recipient-1234"
}
],
"shipping": [{"recipient": {"given_name": "John",
"family_name": "Doe",
"email": "john.doe@klarna.com",
"phone": "844-552-7621",
"attention": "string"
},
"address": {"street_address": "800 N. High St",
"street_address2": "Ste. 400",
"postal_code": "43215",
"city": "Columbus",
"region": "OH",
"country": "US"
},
"shipping_option": {"shipping_type": "TO_DOOR",
"shipping_type_attributes": ["SIGNATURE_REQUIRED"
],
"shipping_carrier": "DHL"
},
"shipping_reference": "DHL-123456"
}
],
"customer": {"given_name": "John",
"family_name": "Doe",
"email": "john.doe@klarna.com",
"phone": "844-552-7621",
"address": {"street_address": "800 N. High St",
"street_address2": "Ste. 400",
"postal_code": "43215",
"city": "Columbus",
"region": "OH",
"country": "US"
},
"customer_accounts": [{"account_identifier": "acc_stripe_1234",
"account_provider_url": "string",
"given_name": "John",
"family_name": "Doe",
"email": "john.doe@klarna.com",
"email_last_verified_at": "2024-01-01T12:00:00Z",
"phone": "844-552-7621",
"phone_last_verified_at": "2024-01-01T12:00:00Z",
"loyalty_level": "LOW",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"last_login": {"occurred_at": "2024-01-01T12:00:00Z",
"login_method": "PHONE_OTP"
},
"purchase_history": [{"number_of_purchases": 2147483647,
"number_of_paid_purchases": 2147483647,
"number_of_disputed_purchases": 2147483647,
"total_amount": 2000,
"currency": "USD",
"payment_method": "CREDIT_CARD",
"first_purchase_at": "2024-01-01T12:00:00Z",
"last_purchase_at": "2024-01-01T12:00:00Z"
}
]
}
],
"customer_device": {"app_identifier": "com.example.merchant",
"device_identifier": "Operating System: Windows 10 Browser: Chrome 91.0.4430.212 Screen Resolution: 1920x1080 Installed Plugins: Adobe Flash Player 32.0.0.465, Java 8 Update 291 Timezone: UTC+02:00 Language: English (United States)",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
"ip_address": "192.168.1.1",
"geolocation": {"country": "US",
"latitude": 40.7128,
"longitude": 74.006
}
}
},
"supplementary_purchase_data": {"additional_data": "\"{\\\"content\\\":{\\\"customer_account_info\\\":[{\\\"unique_account_identifier\\\":\\\"test@gmail.com\\\",\\\"account_registration_date\\\":\\\"2017-02-13T10:49:20Z\\\",\\\"account_last_modified\\\":\\\"2019-03-13T11:45:27Z\\\"}]},\\\"content_type\\\":\\\"application/vnd.klarna.internal.emd-v2+json\\\"}\"\n"
},
"config": {"redirect_url": "https://partner.example/klarna-redirect?payref={klarna.payment_request.payment_reference}",
"request_customer_token": {"scopes": ["payment:customer_not_present"
],
"customer_token_reference": "partner_customer_token_1234"
},
"request_customer_profile": [ ],
"payment_option_id": "string"
},
"interoperability": {"interoperability_token": "string"
}
}

Response samples

application/json

{"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED",
"state_expires_at": "2024-01-01T15:00:00Z",
"state_context": {"distribution": {"url": "https://pay.klarna.com/l/ZjW2Xipgh0tjbrBGD7hzJM"
}
},
"expires_at": "2024-01-02T13:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T13:00:00Z",
"payment_request": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Cancel payment request

Allows you to cancel a payment request.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X DELETE \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/requests/{payment_request_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

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": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

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

Payload
curl
JavaScript
Node.js

application/json

{"currency": "USD",
"payment_amount": 2000,
"payment_transaction_reference": "partner-transaction-reference-4567",
"shipping": [{"recipient": {"given_name": "John",
"family_name": "Doe",
"email": "john.doe@klarna.com",
"phone": "844-552-7621",
"attention": "string"
},
"address": {"street_address": "800 N. High St",
"street_address2": "Ste. 400",
"postal_code": "43215",
"city": "Columbus",
"region": "OH",
"country": "US"
},
"shipping_option": {"shipping_type": "TO_DOOR",
"shipping_type_attributes": ["SIGNATURE_REQUIRED"
],
"shipping_carrier": "DHL"
},
"shipping_reference": "DHL-123456"
}
],
"config": {"capture": false
}
}

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": {"payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
"payment_capture_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:capture:1",
"payment_pricing": {"rate": {"fixed": 100,
"variable": 1200000
},
"details": {"price_plan_id": "krn:partner:global:pricing:payments:price-plan:2a3ced5d-270b-319d-7aa4-a4bcf3a2f4b6",
"program_id": "krn:partner:global:pricing:payments:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
"price_plan_rate": {"fixed": 100,
"variable": 1200000,
"price_cap": 3100000
},
"country": "US",
"merchant_category_code": "5117",
"discount": {"fixed": 0,
"variable": 0
},
"penalty": {"fixed": 0,
"variable": 0
},
"price_cap_applied": false,
"evaluated_at": "2024-01-01T13: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": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Callback payload samples

POST: Webhook callback

application/json

The payment request has been confirmed and the payment is authorized.

{"metadata": {"event_type": "payment.request.state-change.authorized",
"event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
"event_version": "v1",
"occurred_at": "2024-01-01T12:00:00Z",
"account_id": "krn:partner:account:206bbb83-9b6e-46fa-940d-337153c04a58",
"product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
"webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
"live": true
},
"payload": {"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_reference": "partner-payref-1234",
"merchant_reference": "order-5678",
"state": "AUTHORIZED",
"previous_state": "PENDING_CONFIRMATION",
"payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
"payment_capture_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:capture:1"
}
}

Cancel a payment confirmation token

This cancels a payment request pending confirmation, it is only possible if the payment request has the state PENDING_CONFIRMATION.

You may use this if you decide not to confirm a Payment Request that is pending confirmation.

The Payment Request itself will not be canceled, and will revert to the state SUBMITTED with state reason CONFIRMATION_TOKEN_CANCELED.

Request

Security:

klarna_api_keyklarna_partner_account

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 cancel. Example: krn:payment:eu1:confirmation-token:e15432a5-ebcc-45bc-944c-e61399db597b

Responses

200

Confirmation canceled

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

delete/v1/accounts/{account_id}/payment/confirmation-tokens/{payment_confirmation_token}

Request samples

curl
JavaScript
Node.js

curl -i -X DELETE \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/confirmation-tokens/{payment_confirmation_token}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

Response samples

application/json

{"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED",
"state_expires_at": "2024-01-01T15:00:00Z",
"state_context": {"distribution": {"url": "https://pay.klarna.com/l/ZjW2Xipgh0tjbrBGD7hzJM"
}
},
"expires_at": "2024-01-02T13:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T13:00:00Z",
"payment_request": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Callback payload samples

POST: Webhook callback

application/json

The payment request has been submitted to Klarna.

{"metadata": {"event_type": "payment.request.state-change.submitted",
"event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
"event_version": "v1",
"occurred_at": "2024-01-01T12:00:00Z",
"account_id": "krn:partner:account:206bbb83-9b6e-46fa-940d-337153c04a58",
"product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
"webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
"live": true
},
"payload": {"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_reference": "partner-payref-1234",
"merchant_reference": "order-5678",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED"
}
}

Payment Token API

Charge a tokenized customer for a subscription or on-demand usage.

Request

Security:

klarna_api_keyklarna_partner_account

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.

Request Body schema: application/json

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

200

The token charge resulted in either a successful authorization (state: AUTHORIZED) or a decline (state: DECLINED).

In the case of a successful authorization, the response body includes the Payment Transaction ID.

If the charge is declined, reference the state_reason to determine if the token is eligible for retry.

201

The token charge was declined and the step-up flow was activated for the customer. As a result, the returned state will be marked as SUBMITTED with state reason STEP_UP_REQUIRED. The response body includes the stateContext, which provides the distribution URL that the customer must be redirected to for payment authorization.

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/v1/accounts/{account_id}/payment/token/charge

Request samples

Payload
curl
JavaScript
Node.js

application/json

Charge a customer for a previously created subscription for a customer that is not present

{"currency": "USD",
"payment_amount": 500,
"acquiring_channel": "ECOMMERCE",
"line_items": [{"name": "Black fountain pen ink",
"quantity": 1,
"total_amount": 500
}
],
"subscriptions": [{"subscription_reference": "INK_SUBSCRIPTION",
"billing_plan": {"next_billing_at": "2024-03-01"
}
}
],
"config": {"customer_present": false,
"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}",
"customer_token": "krn:partner:us1:live:identity:customer-token:v1:vVQGmYzlfsQ16dko3jcwY5lV8hBgKs9a.96e12495afdc88be3c407087076deabcf50f626242f97c0169779fac4a9acc8f"
}
}

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": {"payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
"payment_capture_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0:capture:1"
},
"expires_at": "2024-01-02T13:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T13:00:00Z",
"payment_request": {"currency": "USD",
"payment_amount": 1000,
"config": {"redirect_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
}
}
}

Callback payload samples

POST: Webhook callback

application/json

The payment request has been submitted to Klarna.

{"metadata": {"event_type": "payment.request.state-change.submitted",
"event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
"event_version": "v1",
"occurred_at": "2024-01-01T12:00:00Z",
"account_id": "krn:partner:account:206bbb83-9b6e-46fa-940d-337153c04a58",
"product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
"webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
"live": true
},
"payload": {"payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_reference": "partner-payref-1234",
"merchant_reference": "order-5678",
"state": "SUBMITTED",
"state_reason": "PAYMENT_REQUEST_SUBMITTED"
}
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/transactions/{payment_transaction_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

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": [{"name": "Black fountain pen",
"quantity": 2,
"total_amount": 2000,
"product_url": "https://merchant.example/product/black-fountain-pen-1234567890",
"image_url": "https://merchant.example/image/1234567890.png",
"product_identifier": "1234567890"
},
{"name": "Sales tax",
"quantity": 1,
"total_amount": 100,
"total_tax_amount": 100
}
],
"shipping": [{"recipient": {"given_name": "Klara",
"family_name": "Angel"
},
"address": {"street_address": "629 N High St",
"street_address2": "Suite 300",
"postal_code": "43215",
"city": "Columbus",
"region": "OH",
"country": "US"
}
}
],
"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": {"rate": {"fixed": 100,
"variable": 1200000
},
"details": {"price_plan_id": "krn:partner:global:pricing:payments:price-plan:2a3ced5d-270b-319d-7aa4-a4bcf3a2f4b6",
"program_id": "krn:partner:global:pricing:payments:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
"price_plan_rate": {"fixed": 100,
"variable": 1200000,
"price_cap": 3100000
},
"country": "US",
"merchant_category_code": "5117",
"discount": {"fixed": 0,
"variable": 0
},
"penalty": {"fixed": 0,
"variable": 0
},
"price_cap_applied": false,
"evaluated_at": "2024-01-01T13:00:00Z"
}
}
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

Payload
curl
JavaScript
Node.js

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": [{"name": "Black fountain pen",
"quantity": 2,
"total_amount": 2000,
"product_url": "https://merchant.example/product/black-fountain-pen-1234567890",
"image_url": "https://merchant.example/image/1234567890.png",
"product_identifier": "1234567890"
},
{"name": "Sales tax",
"quantity": 1,
"total_amount": 100,
"total_tax_amount": 100
}
],
"shipping": [{"recipient": {"given_name": "Klara",
"family_name": "Angel"
},
"address": {"street_address": "629 N High St",
"street_address2": "Suite 300",
"postal_code": "43215",
"city": "Columbus",
"region": "OH",
"country": "US"
}
}
],
"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": {"rate": {"fixed": 100,
"variable": 1200000
},
"details": {"price_plan_id": "krn:partner:global:pricing:payments:price-plan:2a3ced5d-270b-319d-7aa4-a4bcf3a2f4b6",
"program_id": "krn:partner:global:pricing:payments:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
"price_plan_rate": {"fixed": 100,
"variable": 1200000,
"price_cap": 3100000
},
"country": "US",
"merchant_category_code": "5117",
"discount": {"fixed": 0,
"variable": 0
},
"penalty": {"fixed": 0,
"variable": 0
},
"price_cap_applied": false,
"evaluated_at": "2024-01-01T13:00:00Z"
}
}
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

Payload
curl
JavaScript
Node.js

application/json

Shows a capture request with capture amount and line items

{"capture_amount": 5000,
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}

Response samples

application/json

Shows a successful payment capture response

{"payment_capture_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:capture:1",
"capture_amount": 5000,
"capture_reference": "capture-reference-123",
"captured_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
],
"shipments": [{"delivery": {"tracking_number": "DHL123456789",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL123456789&brand=DHL",
"shipping_carrier": "DHL",
"shipping_type": "TO_DOOR",
"shipping_type_attribute": "SIGNATURE_REQUIRED",
"estimated_delivery_date": "2024-01-05"
},
"return": {"tracking_number": "DHL987654321",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL987654321&brand=DHL",
"shipping_carrier": "DHL"
}
}
]
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

Payload
curl
JavaScript
Node.js

application/json

Shows a refund request with refund amount and line items

{"refund_amount": 5000,
"refund_reference": "refund-reference-123",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}

Response samples

application/json

Shows a successful response to a refund operation on a payment transaction.

{"payment_refund_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:refund:1",
"refund_amount": 5000,
"refund_reference": "refund-reference-123",
"refunded_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X POST \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/transactions/{payment_transaction_id}/void' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

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": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
},
{"name": "Custom Berlin Wall Art Skateboard",
"quantity": 1,
"total_amount": 10000,
"product_url": "https://merchant.example/product/custom-berlin-wall-art-skateboard-5566778899",
"image_url": "https://merchant.example/image/5566778899.png",
"product_identifier": "5566778899"
}
],
"shipping": [{"recipient": {"given_name": "Klara",
"family_name": "Angel"
},
"address": {"street_address": "Kurfürstendamm 100",
"postal_code": "10709",
"city": "Berlin",
"region": "Berlin",
"country": "DE"
}
}
],
"captures": [{"payment_capture_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:capture:1",
"capture_amount": 5000,
"capture_reference": "capture-reference-123",
"captured_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
],
"shipments": [{"delivery": {"tracking_number": "DHL123456789",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL123456789&brand=DHL",
"shipping_carrier": "DHL",
"shipping_type": "TO_DOOR",
"shipping_type_attribute": "SIGNATURE_REQUIRED",
"estimated_delivery_date": "2024-01-05"
},
"return": {"tracking_number": "DHL987654321",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL987654321&brand=DHL",
"shipping_carrier": "DHL"
}
}
]
}
],
"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": {"rate": {"fixed": 100,
"variable": 1200000
},
"details": {"price_plan_id": "krn:price-plan:12345678",
"program_id": "krn:partner:global:pricing:payments:program:a5cd46f7e-573d-4b02-bab8-1f1c0e343291",
"price_plan_rate": {"fixed": 100,
"variable": 1200000,
"price_cap": 3100000
},
"country": "US",
"merchant_category_code": "5117",
"discount": {"fixed": 0,
"variable": 0
},
"penalty": {"fixed": 0,
"variable": 0
},
"price_cap_applied": false,
"evaluated_at": "2024-01-01T13:00:00Z"
}
}
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/captures/{payment_capture_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

Response samples

application/json

Shows a successful payment capture response

{"payment_capture_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:capture:1",
"capture_amount": 5000,
"capture_reference": "capture-reference-123",
"captured_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
],
"shipments": [{"delivery": {"tracking_number": "DHL123456789",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL123456789&brand=DHL",
"shipping_carrier": "DHL",
"shipping_type": "TO_DOOR",
"shipping_type_attribute": "SIGNATURE_REQUIRED",
"estimated_delivery_date": "2024-01-05"
},
"return": {"tracking_number": "DHL987654321",
"tracking_url": "https://www.dhl.com/en/express/tracking.html?AWB=DHL987654321&brand=DHL",
"shipping_carrier": "DHL"
}
}
]
}

Refund Payment Capture

Request to refund a payment capture.

Request

Security:

klarna_api_keyklarna_partner_account

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

Payload
curl
JavaScript
Node.js

application/json

Shows a refund request with refund amount and line items

{"refund_amount": 5000,
"refund_reference": "refund-reference-123",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}

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",
"refund_amount": 5000,
"refund_reference": "refund-reference-123",
"refunded_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}

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.

Request

Security:

klarna_api_keyklarna_partner_account

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

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/refunds/{payment_refund_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Klarna-Partner-Account: YOUR_API_KEY_HERE'

Response samples

application/json

Shows a successful response to a refund operation on a payment transaction.

{"payment_refund_id": "krn:payment:eu1:transaction:bc42b6ff-b222-463c-b4b2-d8d6a82e0162:refund:1",
"refund_amount": 5000,
"refund_reference": "refund-reference-123",
"refunded_at": "2024-01-02T13:00:00Z",
"line_items": [{"name": "Oversized vintage trabant tee",
"quantity": 2,
"total_amount": 5000,
"product_url": "https://merchant.example/product/oversized-vintage-trabant-tee-3344556677",
"image_url": "https://merchant.example/image/3344556677.png",
"product_identifier": "1234567890"
}
]
}