API & SDKsSupport

Klarna Partner Management API (release/3)

Download OpenAPI specification:Download

URL: https://www.klarna.com

Release 3

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

Credentials

Management of own Account credentials.

Create a credential for your own account

Create a new credential

Request
Security:
klarna_api_key
Request Body schema: application/json
description
string^[a-zA-Z0-9\-:;., _]{0,100}$

Description provided by the partner when creating a set of credentials

type
required
string

Indicates the type of credentials to be created. API for an api-key and CLIENT for a clientId which can be used by the Web SDK.

Enum: "CLIENT" "API"
environment
required
string

Indicates the environment (TEST or LIVE) for which the credentials should be created,

Enum: "LIVE" "TEST"
Responses
200

Credential created

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

post/v1/account/credentials
Request samples
application/json
{
  • "description": "Test Client Credentials",
  • "type": "CLIENT",
  • "environment": "TEST"
}
Response samples
application/json
{
  • "credential_id": "376e67bb-8171-4dba-b330-9130dd0798e4",
  • "description": "Test Client Credentials",
  • "type": "CLIENT",
  • "environment": "TEST",
  • "client_id": "klarna_test_client_cADfmmYgMtpcgVi9toAaPXeCktHS2TKS7UrWxvxtWdCVq3uLpQXZVSPZNWEcLACDpvHZVmCWeFVD44fygezrVNU4ta9jdAR4H3evwjCKTTaRAs2sQDHSpN2TMzWVwrVpoZPacgTTVhXiWrNsXp23aEvdiLi"
}

List Credentials

List all credentials associated with the current account

Request
Security:
klarna_api_key
Responses
200

Credentials found

401

Unauthorized, the request was not authorized.

500

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

get/v1/account/credentials
Request samples
curl -i -X GET \
  https://api-global.klarna.com/v1/account/credentials \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "credentials": [
    ]
}

Disable Credential

Disable a Credential.

Request
Security:
klarna_api_key
path Parameters
credential_id
required
string <uuid> (CredentialIdentifier) ([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Identifier of the Credential

Example: 206bbb83-9b6e-46fa-940d-337153c04a58
Responses
204

No Content

401

Unauthorized, the request was not authorized.

500

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

delete/v1/account/credentials/{credential_id}
Request samples
curl -i -X DELETE \
  'https://api-global.klarna.com/v1/account/credentials/{credential_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "error_id": "1653c9db-454b-4222-8265-4c7ca209f630",
  • "error_type": "ACCESS_ERROR",
  • "error_code": "UNAUTHORIZED",
  • "error_message": "The presented credentials failed authentication"
}

Payment Distribution Profiles

A Payment Distribution has a set of pre-defined profiles that can be used when handling Payment Products. An account onboarded to a Payment Product needs to have one Distribution Profile associated with it.

List all Payment Distribution profiles.

Fetches all payments distribution product profile, which can be selected to be used on a new Payment Product onboarding.

Request
Security:
klarna_api_key
Responses
200

Payment Distribution Profiles retrieved

401

Unauthorized, the request was not authorized.

500

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

get/v1/distribution/products/payment/profiles
Request samples
curl -i -X GET \
  https://api-global.klarna.com/v1/distribution/products/payment/profiles \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Onboard

The onboard API allows the authenticated Account to create a fully functional account with associated business entity, product, websites etc.

Onboard a merchant

Onboard a new merchant. This request creates all necessary entries to have a fully functional account for the merchant.

Request
Security:
klarna_api_key
Request Body schema: application/json
account_reference
required
string

Reference for the Distribution Partner in relation to the merchant being onboarded.

account_name
required
string

The name of the account, business name or similar.

required
object

The account owner details

account_group_reference
string

Partners can group several merchant accounts under given account_group_reference

account_group_id
string (AccountGroupIdentifier)

Group id assigned by Klarna for a given account_group_reference. Partners can use this parameter as an alternative to account_group_reference to manage an account group.

required
Array of objects (PaymentProductData)

Information about which products are being configured for this merchant

required
object (ChannelData)

Root channel object

object (ExtraAccountData)

Root extra account data object

Responses
200

Merchant account created

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

Callbacks
postWebhook callback
post/v1/distribution/onboard
Request samples
application/json
{
  • "account_reference": "M123786123412",
  • "account_name": "John Doe Stakehouse",
  • "account_owner": {
    },
  • "products": [
    ],
  • "channel": {}
}
Response samples
application/json
{
  • "account_id": "krn:partner:global:account:live:LWT2XJSE",
  • "account_reference": "M123786123412",
  • "account_name": "Merchant ABC US",
  • "state": "PARTIALLY_OPERATIONAL",
  • "state_reason": "INITIAL_SETUP"
}
Callback payload samples
POST: Webhook callback
application/json

The webhook is triggered once the distribution partner's account state changes.

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

Accounts

The Accounts API allows the authenticated Partner to create, read, manage the different Accounts it has access to.

Read Account

Read all details from a Account which the acting Account has read access on.

Request
Security:
klarna_api_key
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
Responses
200

Account details

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "account_id": "krn:partner:global:account:live:LWT2XJSE",
  • "account_reference": "M123786123412",
  • "account_name": "John Doe Stakehouse",
  • "account_group_reference": "all-john-doe-restaurants",
  • "account_group_id": "krn:partner:global:account:group:b0ac4fb5-2975-4417-ae76-f2ac86fb6c6d",
  • "account_owner": {
    },
  • "state": "PARTIALLY_OPERATIONAL",
  • "state_reason": "INITIAL_SETUP"
}

Update Account

Update details from an Account which the acting Account has write access on.

Request
Security:
klarna_api_key
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
Request Body schema: application/json
account_reference
string

Reference for the Distribution Partner in relation to the merchant being onboarded.

account_name
string

The name of the account, business name or similar.

object (AccountOwner)

The account owner details

Responses
200

Account details

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.

500

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

patch/v1/accounts/{account_id}
Request samples
application/json
{
  • "account_reference": "M123786123412",
  • "account_name": "John Doe Stakehouse",
  • "account_owner": {
    }
}
Response samples
application/json
{
  • "account_id": "krn:partner:global:account:live:LWT2XJSE",
  • "account_reference": "M123786123412",
  • "account_name": "John Doe Stakehouse",
  • "account_group_reference": "all-john-doe-restaurants",
  • "account_group_id": "krn:partner:global:account:group:b0ac4fb5-2975-4417-ae76-f2ac86fb6c6d",
  • "account_owner": {
    },
  • "state": "PARTIALLY_OPERATIONAL",
  • "state_reason": "INITIAL_SETUP"
}

Payment Products

The Accounts API allows the authenticated Partner to create, read, manage the Payment Products on an Account.

Get all account payment products

Obtains a list of all payment products associated with the account

Request
Security:
klarna_api_key
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
Responses
200

List of payment products

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/products/payment
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/products/payment' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Patch a given Payment Product information

Update information from a given payment product associated with the account.

Request
Security:
klarna_api_key
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
required
PaymentProductDefault (string) or PaymentProductIdentifier (string)

Identifier of the Payment Product the action is done on behalf of. Use default to apply the action on the unique payment product.

Request Body schema: application/json
merchant_category_code
string (MerchantCategoryCode)

The four-digit number that is used to classify the type of goods or services offered by a business.

Responses
200

Payment product information updated successfully.

400

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

401

Unauthorized, the request was not authorized.

500

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

patch/v1/accounts/{account_id}/products/payment/{product_id}
Request samples
application/json
{
  • "merchant_category_code": "5411"
}
Response samples
application/json
{
  • "distribution_profile_id": "krn:partner:global:account:distribution-profile:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "type": "PAYMENT",
  • "merchant_category_code": "5411"
}

Suspend a Payment Product

Suspends the Payment Product on an account for the given reason.

Request
Security:
klarna_api_key
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
required
PaymentProductDefault (string) or PaymentProductIdentifier (string)

Identifier of the Payment Product the action is done on behalf of. Use default to apply the action on the unique payment product.

Request Body schema: application/json
reason
required
string

The reason for suspending the Payment Product

Enum: "FRAUD" "VOLUNTARY"
reason_details
required
string <= 500

Allows the partner to pass additional information regarding the suspension

Responses
200

Sub account suspended

401

Unauthorized, the request was not authorized.

500

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

Callbacks
postWebhook callback
post/v1/accounts/{account_id}/products/payment/{product_id}/disable
Request samples
application/json
{
  • "reason": "FRAUD",
  • "reason_details": "Fraudulent activity detected"
}
Response samples
application/json
{
  • "product_id": "krn:partner:global:account:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "type": "PAYMENT",
  • "distribution_profile_id": "krn:partner:global:account:distribution-profile:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "merchant_category_code": "5411",
  • "state": "DISABLED",
  • "state_reason": "FRAUD_BY_PARTNER",
  • "state_context": {
    }
}
Callback payload samples
POST: Webhook callback
application/json

The webhook is triggered once the distribution partner's account payment product is disabled.

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

Revert suspension of a Payment Product

Revert suspension of the Payment Product on an account.

Request
Security:
klarna_api_key
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
required
PaymentProductDefault (string) or PaymentProductIdentifier (string)

Identifier of the Payment Product the action is done on behalf of. Use default to apply the action on the unique payment product.

Responses
200

Sub account suspension reverted

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

Callbacks
postWebhook callback
post/v1/accounts/{account_id}/products/payment/{product_id}/enable
Request samples
curl -i -X POST \
  'https://api-global.klarna.com/v1/accounts/{account_id}/products/payment/{product_id}/enable' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "product_id": "krn:partner:global:account:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "type": "PAYMENT",
  • "distribution_profile_id": "krn:partner:global:account:distribution-profile:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "merchant_category_code": "5411",
  • "state": "ENABLED",
  • "state_reason": "APPROVED"
}
Callback payload samples
POST: Webhook callback
application/json

The webhook is triggered once the distribution partner's account payment product is enabled.

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

Suspend a Payment ProductDeprecated

Suspends the Payment Product on an account for the given reason.

Request
Security:
klarna_api_key
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
Request Body schema: application/json
reason
required
string

The reason for suspending the Payment Product

Enum: "FRAUD" "VOLUNTARY"
reason_details
required
string <= 500

Allows the partner to pass additional information regarding the suspension

Responses
200

Sub account suspended

401

Unauthorized, the request was not authorized.

500

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

Callbacks
postWebhook callback
post/v1/accounts/{account_id}/products/payment/disable
Request samples
application/json
{
  • "reason": "FRAUD",
  • "reason_details": "Fraudulent activity detected"
}
Response samples
application/json
{
  • "product_id": "krn:partner:global:account:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "type": "PAYMENT",
  • "distribution_profile_id": "krn:partner:global:account:distribution-profile:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "merchant_category_code": "5411",
  • "state": "DISABLED",
  • "state_reason": "FRAUD_BY_PARTNER",
  • "state_context": {
    }
}
Callback payload samples
POST: Webhook callback
application/json

The webhook is triggered once the distribution partner's account payment product is disabled.

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

Revert suspension of a Payment ProductDeprecated

Revert suspension of the Payment Product on an account.

Request
Security:
klarna_api_key
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
Responses
200

Sub account suspension reverted

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

Callbacks
postWebhook callback
post/v1/accounts/{account_id}/products/payment/enable
Request samples
curl -i -X POST \
  'https://api-global.klarna.com/v1/accounts/{account_id}/products/payment/enable' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "product_id": "krn:partner:global:account:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "type": "PAYMENT",
  • "distribution_profile_id": "krn:partner:global:account:distribution-profile:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "merchant_category_code": "5411",
  • "state": "ENABLED",
  • "state_reason": "APPROVED"
}
Callback payload samples
POST: Webhook callback
application/json

The webhook is triggered once the distribution partner's account payment product is enabled.

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

Websites

The Accounts API allows the authenticated Partner to create, read, manage the Web Domains channel on an Account.

List all website channels

Fetch all website channels of an account

Request
Security:
klarna_api_key
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
Responses
200

Website channel found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/channel/websites
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/channel/websites' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Update a website channel

Update a website channel from an account

Request
Security:
klarna_api_key
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
website_id
required
string (WebsitesIdentifier)

Unique identifier assigned by Klarna to this website

Example: krn:partner:global:account:channel:website:206bbb83-9b6e-46fa-940d-337153c04a58
Request Body schema: application/json
urls
Array of strings

The applicable base domain urls for the website

website_name
string

The website's name.

website_reference
string

The reference assigned by the partner to this website

channel_collection_reference
string

The reference to the channel collection associated to the website object

channel_collection_id
string (CollectionsIdentifier)

Unique identifier assigned by Klarna to the channel collection defined

Responses
200

Website channel 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.

500

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

patch/v1/accounts/{account_id}/channel/websites/{website_id}
Request samples
application/json
{
  • "urls": [],
  • "website_name": "John Doe Stakehouse",
  • "website_reference": "999888777",
  • "channel_collection_reference": "online-stores",
  • "channel_collection_id": "krn:partner:global:account:channel:collection:cad7a851-8f59-47ed-8b1f-e1d61a0e817c"
}
Response samples
application/json
{
  • "website_id": "krn:partner:global:account:channel:website:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "urls": [],
  • "website_name": "John Doe Stakehouse",
  • "website_reference": "999888777",
  • "channel_collection_reference": "online-stores",
  • "channel_collection_id": "krn:partner:global:account:channel:collection:cad7a851-8f59-47ed-8b1f-e1d61a0e817c"
}

Collections

The Accounts API allows the authenticated Partner to create, read, manage the Collections channel on an Account.

List all collection channels

Fetch all collection channels of an account

Request
Security:
klarna_api_key
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
Responses
200

Collection channel found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/channel/collections
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/channel/collections' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[]

Update a collection channel

Update a collection channel from an account

Request
Security:
klarna_api_key
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
collection_id
required
string (CollectionsIdentifier)

Unique identifier assigned by Klarna to the channel collection defined

Example: krn:partner:global:account:channel:collection:cad7a851-8f59-47ed-8b1f-e1d61a0e817c
Request Body schema: application/json
collection_reference
string

The collection reference which can be assigned to a given websites[]

object (Branding)

The branding assets defined for the collection

object (SupportContact)

The list of customer support contact point

Array of objects (SocialMediaLinks)
Responses
200

Collection channel 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.

500

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

patch/v1/accounts/{account_id}/channel/collections/{collection_id}
Request samples
application/json
{}
Response samples
application/json
{}

Account information

The Accounts API allows the authenticated Partner to provide additional information for a given merchant, e.g the IP address used by the merchant when signing up for an account with the partner and the corresponding timestamp

Fetch the account information

Fetch the account information

Request
Security:
klarna_api_key
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
Responses
200

Business information found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/account-information
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/account-information' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "account_created_from_ip": "192.168.1.1",
  • "account_created_at": "2024-01-01T12:00:00Z"
}

Update the account information

Update the account information of an existing account

Request
Security:
klarna_api_key
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
Request Body schema: application/json
account_created_from_ip
string <ip_address> (IpAddress) ^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25...

Valid IPV4 or IPV6 address

account_created_at
string <date-time> (Timestamp) ^[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]T[...

Timestamp in ISO 8601 with timezone e.g. 2024-01-01T12:00:00Z

Responses
200

Account information 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.

409

Account information can only be set once

500

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

patch/v1/accounts/{account_id}/extra-account-data/account-information
Request samples
application/json
{
  • "account_created_from_ip": "192.168.1.1",
  • "account_created_at": "2024-01-01T12:00:00Z"
}
Response samples
application/json
{
  • "account_created_from_ip": "192.168.1.1",
  • "account_created_at": "2024-01-01T12:00:00Z"
}

Business information

The Accounts API allows the authenticated Partner to provide additional detailed business information for a given merchant, for example the business registration address and registration number.

Fetch the business information for the account

Fetch the business information for the account

Request
Security:
klarna_api_key
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
Responses
200

Business information found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/business-information
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/business-information' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "business_name": "John Doe LLC",
  • "business_entity_type": "LIMITED_LIABILITY_COMPANY",
  • "registration_authority": "Ohio",
  • "registration_number": "12345678",
  • "tax_registration_number": "999-999-999",
  • "financial_registration_number": "12345678",
  • "operating_address": {
    },
  • "registration_address": {
    }
}

Update the business information

Update the business information of an existing account

Request
Security:
klarna_api_key
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
Request Body schema: application/json
business_name
string

Registered Business name

business_entity_type
string

Legal status of the business

Enum: "SOLE_TRADER" "STATE_OWNED_COMPANY" "ASSOCIATION" "PUBLIC_LIMITED_COMPANY" "PRIVATE_UNLIMITED_COMPANY" "COOPERATIVE" "FOUNDATION" "NON_PROFIT_ORGANISATION" "PARTNERSHIP" "LIMITED_LIABILITY_COMPANY" "TRUST" "UNKNOWN"
registration_authority
string

The authority / local court where the company is registered

registration_number
string

Identification number assigned to a business entity when it is registered with a government authority

tax_registration_number
string

The unique number that identifies a taxable business or non-taxable legal entity that is registered for VAT/Sales Tax

financial_registration_number
string

The financial license number as registered with the authorities

object

The root object for the operational business address

object

The root object for the registered business address

Responses
200

Business information 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.

500

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

patch/v1/accounts/{account_id}/extra-account-data/business-information
Request samples
application/json
{
  • "business_name": "John Doe LLC",
  • "business_entity_type": "LIMITED_LIABILITY_COMPANY",
  • "registration_authority": "Ohio",
  • "registration_number": "12345678",
  • "tax_registration_number": "999-999-999",
  • "financial_registration_number": "12345678",
  • "operating_address": {
    },
  • "registration_address": {
    }
}
Response samples
application/json
{
  • "business_name": "John Doe LLC",
  • "business_entity_type": "LIMITED_LIABILITY_COMPANY",
  • "registration_authority": "Ohio",
  • "registration_number": "12345678",
  • "tax_registration_number": "999-999-999",
  • "financial_registration_number": "12345678",
  • "operating_address": {
    },
  • "registration_address": {
    }
}

Beneficiary information

The Accounts API allows the authenticated Partner to create, read, manage the Beneficiary Information on an Account.

Register a stakeholder

Register a stakeholder on an existing account

Request
Security:
klarna_api_key
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
Request Body schema: application/json
given_name
string [ 1 .. 99 ] characters

The stakeholder given name

family_name
string [ 1 .. 99 ] characters

The stakeholder family name

object

The root object for the stakeholder address

date_of_birth
string (DateOfBirth) ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Date of birth of the person on the format YYYY-MM-DD

object

National Identification Number for a person. The number is formatted according to country standards.

roles
required
Array of strings

List of roles this stakeholder has in the business

Items Enum: "LEGAL_REPRESENTATIVE" "ALTERNATIVE_BENEFICIAL_OWNER" "ULTIMATE_BENEFICIAL_OWNER" "OWNER"
Responses
200

Stakeholder registered

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

post/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders
Request samples
application/json
{
  • "given_name": "John",
  • "family_name": "Doe",
  • "address": {
    },
  • "date_of_birth": "1970-01-01",
  • "national_identification": {
    },
  • "roles": [
    ]
}
Response samples
application/json
{
  • "stakeholder_id": "krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "given_name": "John",
  • "family_name": "Doe",
  • "address": {
    },
  • "date_of_birth": "1970-01-01",
  • "national_identification": {
    },
  • "roles": [
    ]
}

List all stakeholders

Fetch all stakeholders on an account

Request
Security:
klarna_api_key
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
Responses
200

Stakeholders found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Retrieve a stakeholder

Retrieve a collection channel from an existing account

Request
Security:
klarna_api_key
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
stakeholder_id
required
string (StakeholderIdentifier)

Unique identifier for this stakeholder

Example: krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58
Responses
200

Stakeholder found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders/{stakeholder_id}
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders/{stakeholder_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "stakeholder_id": "krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "given_name": "John",
  • "family_name": "Doe",
  • "address": {
    },
  • "date_of_birth": "1970-01-01",
  • "national_identification": {
    },
  • "roles": [
    ]
}

Update a stakeholder

Update a stakeholder on an account

Request
Security:
klarna_api_key
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
stakeholder_id
required
string (StakeholderIdentifier)

Unique identifier for this stakeholder

Example: krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58
Request Body schema: application/json
given_name
string [ 1 .. 99 ] characters

The stakeholder given name

family_name
string [ 1 .. 99 ] characters

The stakeholder family name

object

The root object for the stakeholder address

date_of_birth
string (DateOfBirth) ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Date of birth of the person on the format YYYY-MM-DD

object

National Identification Number for a person. The number is formatted according to country standards.

roles
required
Array of strings

List of roles this stakeholder has in the business

Items Enum: "LEGAL_REPRESENTATIVE" "ALTERNATIVE_BENEFICIAL_OWNER" "ULTIMATE_BENEFICIAL_OWNER" "OWNER"
Responses
200

Stakeholder updated

400

Bad Request

401

Unauthorized, the request was not authorized.

500

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

patch/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders/{stakeholder_id}
Request samples
application/json
{
  • "given_name": "John",
  • "family_name": "Doe",
  • "address": {
    },
  • "date_of_birth": "1970-01-01",
  • "national_identification": {
    },
  • "roles": [
    ]
}
Response samples
application/json
{
  • "stakeholder_id": "krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58",
  • "given_name": "John",
  • "family_name": "Doe",
  • "address": {
    },
  • "date_of_birth": "1970-01-01",
  • "national_identification": {
    },
  • "roles": [
    ]
}

Delete a Stakeholder

Remove a given stakeholder from an account

Request
Security:
klarna_api_key
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
stakeholder_id
required
string (StakeholderIdentifier)

Unique identifier for this stakeholder

Example: krn:partner:global:account:stakeholder:206bbb83-9b6e-46fa-940d-337153c04a58
Responses
204

Stakeholder removed

401

Unauthorized, the request was not authorized.

500

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

delete/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders/{stakeholder_id}
Request samples
curl -i -X DELETE \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/beneficiary-information/stakeholders/{stakeholder_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "error_id": "1653c9db-454b-4222-8265-4c7ca209f630",
  • "error_type": "ACCESS_ERROR",
  • "error_code": "UNAUTHORIZED",
  • "error_message": "The presented credentials failed authentication"
}

Settlement information

The Accounts API allows the authenticated Partner to share the settlement information for a given merchant which Klarna would solely use for KYB (Know Your Business) purposes.

Retrieve settlement information

Retrieve the settlement information

Request
Security:
klarna_api_key
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
Responses
200

Settlement information found

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

500

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

get/v1/accounts/{account_id}/extra-account-data/settlement-information
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/settlement-information' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "settlement_enabled": true,
  • "settlement_enabled_at": "2024-01-01T12:00:00Z"
}

Update settlement information

Update settlement information

Request
Security:
klarna_api_key
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
Request Body schema: application/json
settlement_enabled
boolean

Are payouts enabled

settlement_enabled_at
string <date-time> (Timestamp) ^[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]T[...

Timestamp in ISO 8601 with timezone e.g. 2024-01-01T12:00:00Z

Responses
200

Settlement information 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.

500

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

patch/v1/accounts/{account_id}/extra-account-data/settlement-information
Request samples
application/json
{
  • "settlement_enabled": true,
  • "settlement_enabled_at": "2024-01-01T12:00:00Z"
}
Response samples
application/json
{
  • "settlement_enabled": true,
  • "settlement_enabled_at": "2024-01-01T12:00:00Z"
}

Add bank account information

Add bank account information

Request
Security:
klarna_api_key
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
Request Body schema: application/json
bank_account_type
required
string (BankAccountType)

The settlement type available for a given currency

account_holder
string (AccountHolder)

The account holder name

bic
required
string (Bic) [ 8 .. 11 ] characters

The bank's 8- or 11-character BIC or SWIFT code.

iban
required
string

The international bank account number as defined in the ISO-13616 standard.

Responses
200

Bank account information added

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.

500

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

post/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts
Request samples
application/json
{
  • "bank_account_type": "IBAN",
  • "account_holder": "John Doe Stakehouse",
  • "bic": "NDEASEGGXXX",
  • "iban": "SE4550000000058398257466"
}
Response samples
application/json
{
  • "bank_account_id": "krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2",
  • "bank_account_type": "IBAN",
  • "account_holder": "John Doe Stakehouse",
  • "bic": "NDEASEGGXXX",
  • "iban": "SE4550000000058398257466"
}

List all bank account information

List all bank account information

Request
Security:
klarna_api_key
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
Responses
200

Bank account information found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {
    }
]

Retrieve bank account information

Retrieve a bank account information from an existing account

Request
Security:
klarna_api_key
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
bank_account_id
required
string (BankAccountIdentifier)

Unique identifier assigned to the bank information provided

Example: krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2
Responses
200

Stakeholder found

401

Unauthorized, the request was not authorized.

500

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

get/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts/{bank_account_id}
Request samples
curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts/{bank_account_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "bank_account_id": "krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2",
  • "bank_account_type": "IBAN",
  • "account_holder": "John Doe Stakehouse",
  • "bic": "NDEASEGGXXX",
  • "iban": "SE4550000000058398257466"
}

Update bank account information

Update bank detail information for a given account

Request
Security:
klarna_api_key
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
bank_account_id
required
string (BankAccountIdentifier)

Unique identifier assigned to the bank information provided

Example: krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2
Request Body schema: application/json
bank_account_type
required
string (BankAccountType)

The settlement type available for a given currency

account_holder
string (AccountHolder)

The account holder name

bic
required
string (Bic) [ 8 .. 11 ] characters

The bank's 8- or 11-character BIC or SWIFT code.

iban
required
string

The international bank account number as defined in the ISO-13616 standard.

Responses
200

Bank account information 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.

500

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

patch/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts/{bank_account_id}
Request samples
application/json
{
  • "bank_account_type": "IBAN",
  • "account_holder": "John Doe Stakehouse",
  • "bic": "NDEASEGGXXX",
  • "iban": "SE4550000000058398257466"
}
Response samples
application/json
{
  • "bank_account_id": "krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2",
  • "bank_account_type": "IBAN",
  • "account_holder": "John Doe Stakehouse",
  • "bic": "NDEASEGGXXX",
  • "iban": "SE4550000000058398257466"
}

Delete bank account information

Remove bank account information from an account

Request
Security:
klarna_api_key
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
bank_account_id
required
string (BankAccountIdentifier)

Unique identifier assigned to the bank information provided

Example: krn:partner:global:settlement-information:bank-account:56f77163-bc1b-46c8-a245-e251ff65e3d2
Responses
204

Bank account information removed

401

Unauthorized, the request was not authorized.

500

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

delete/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts/{bank_account_id}
Request samples
curl -i -X DELETE \
  'https://api-global.klarna.com/v1/accounts/{account_id}/extra-account-data/settlement-information/bank-accounts/{bank_account_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "error_id": "1653c9db-454b-4222-8265-4c7ca209f630",
  • "error_type": "ACCESS_ERROR",
  • "error_code": "UNAUTHORIZED",
  • "error_message": "The presented credentials failed authentication"
}
Cookies
Terms of Service
© Klarna 2024