Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Reference Klarna API
version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
description: Sandbox
- url: https://api.mangopay.com
description: Production
- url: https://api-mtls.sandbox.mangopay.com
description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.
**Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.
'
tags:
- name: Klarna
paths:
/v2.01/{ClientId}/payins/payment-methods/klarna:
post:
operationId: klarna_create_klarna_payin
summary: Create a Klarna PayIn
description: '**Note – Timeout after 3 hours**
The Klarna payment session lasts 3 hours, at which point the pay-in fails automatically (result code 101109) if no action has been taken by the user.
**Note – Minimum amount in Production**
In Production, the minimum accepted `DebitedFunds` amount for Klarna is `1` (regardless of currency).
Create a Klarna PayIn'
tags:
- Klarna
parameters:
- name: ClientId
in: path
description: Platform's API account identifier, associated with the API key.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/KlarnaPayInResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAKlarnaPayInRequest'
security:
- oauth2: []
components:
schemas:
StatementDescriptor:
type: string
description: 'Max. length: 10 characters; only alphanumeric and spaces
Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.'
title: StatementDescriptor
Address_SubPropsRequired:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: 'The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.'
Country:
type: string
description: 'Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))
The country of the address.'
required:
- AddressLine1
- City
- PostalCode
- Country
description: The postal address.
title: Address_SubPropsRequired
KlarnaPayInResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the fees.
title: KlarnaPayInResponseFees
Amount:
type: integer
description: The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`.
title: Amount
FlowDescriptorRequestBeneficiariesItems:
type: object
properties:
UserId:
type: string
description: The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in.
title: FlowDescriptorRequestBeneficiariesItems
KlarnaPayInResponseLineItemsItems:
type: object
properties:
Name:
type: string
description: The name of the item.
Quantity:
type: integer
description: The quantity of the item.
UnitAmount:
type: integer
description: The cost of the item, excluding tax.
TaxAmount:
type: integer
description: The tax amount applied to the item.
Sku:
type: string
description: The unique identifier of the line item.
Category:
type: string
description: 'Possible values: `DIGITAL_GOODS`, `PHYSICAL_GOODS`, `DISCOUNT`, `SHIPPING_FEE`, `SALES_TAX`, `GIFT_CARD`, `STORE_CREDIT`, `SURCHARGE`
The category of the item, allowing line items of different types to be distinguished (for example, buyer protection as `DIGITAL_GOODS`).'
Discount:
type: integer
description: The discount applied to the item.
title: KlarnaPayInResponseLineItemsItems
FlowDescriptorResponseBeneficiariesItems:
type: object
properties:
UserId:
type: string
description: The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in.
title: FlowDescriptorResponseBeneficiariesItems
TransactionExecutionDate:
type: integer
description: Unix timestamp (UTC) of the date and time the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`.
title: TransactionExecutionDate
AuthorId:
type: string
description: The unique identifier of the user at the source of the transaction.
title: AuthorId
ProfilingAttemptReference:
type: string
description: 'The unique reference generated for the profiling session, used by the <a href="/guides/fraud-prevention">fraud prevention</a> solution to produce recommendations for the transaction using the profiling data.
**Note:** Parameter not returned by the API. Profiling feature available on request – contact Mangopay <a href="https://hub.mangopay.com/" target="_blank">via the Dashboard</a> for more information.'
title: ProfilingAttemptReference
FlowDescriptorRequest:
type: object
properties:
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorRequestBeneficiariesItems'
description: 'Max. length: 5 items
The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values.'
description: "Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n - `OWNER` whose `KYCLevel` is `REGULAR`\n - `PLATFORM`\n \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`. \n"
title: FlowDescriptorRequest
Shipping_DefaultsBillingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address_SubPropsRequired'
description: '**Default values:** `FirstName`, `LastName`, and `Address` information of the `Billing` object if sent, otherwise of the `AuthorId` (if address values present).
Information about the shipping address. '
title: Shipping_DefaultsBillingUser_Response
CreateAKlarnaPayInRequestDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
required:
- Currency
- Amount
description: Information about the debited funds.
title: CreateAKlarnaPayInRequestDebitedFunds
TransactionStatus:
type: string
description: '**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.'
title: TransactionStatus
CreditedUserId:
type: string
description: '**Default value:** The unique identifier of the owner of the credited wallet.
The unique identifier of the user whose wallet is credited.'
title: CreditedUserId
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
Currency:
type: string
description: '**Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).
The currency of the amount.'
title: Currency
FlowDescriptorResponse:
type: object
properties:
FlowId:
type: string
description: Unique identifier of the payment flow, used by Mangopay for internal purposes.
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorResponseBeneficiariesItems'
description: 'Max. length: 5 items
The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values.'
description: "Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n - `OWNER` whose `KYCLevel` is `REGULAR`\n - `PLATFORM`\n \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`.\n"
title: FlowDescriptorResponse
Address:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: 'The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.'
Country:
type: string
description: 'Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))
The country of the address.'
description: The postal address.
title: Address
TransactionNature:
type: string
description: '**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`
The nature of the transaction, providing more information about the context in which the transaction occurred:
- `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.
- `REPUDIATION` – Automatic withdrawal of funds from the platform''s repudiation wallet as part of the dispute process (when the user has requested a chargeback).
- `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).
- `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute.'
title: TransactionNature
CreateAKlarnaPayInRequestLineItemsItems:
type: object
properties:
Name:
type: string
description: The name of the item.
Quantity:
type: integer
description: The quantity of the item.
UnitAmount:
type: integer
description: The cost of the item, excluding tax.
TaxAmount:
type: integer
description: The tax amount applied to the item.
Sku:
type: string
description: The unique identifier of the line item.
Category:
type: string
description: 'Possible values: `DIGITAL_GOODS`, `PHYSICAL_GOODS`, `DISCOUNT`, `SHIPPING_FEE`, `SALES_TAX`, `GIFT_CARD`, `STORE_CREDIT`, `SURCHARGE`
The category of the item, allowing line items of different types to be distinguished (for example, buyer protection as `DIGITAL_GOODS`).'
Discount:
type: integer
description: The discount applied to the item.
required:
- Name
- Quantity
- UnitAmount
title: CreateAKlarnaPayInRequestLineItemsItems
KlarnaPayInResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: KlarnaPayInResponseDebitedFunds
KlarnaPayInResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
$ref: '#/components/schemas/AuthorId'
DebitedFunds:
$ref: '#/components/schemas/KlarnaPayInResponseDebitedFunds'
description: Information about the debited funds.
CreditedFunds:
$ref: '#/components/schemas/KlarnaPayInResponseCreditedFunds'
description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
Fees:
$ref: '#/components/schemas/KlarnaPayInResponseFees'
description: Information about the fees.
Status:
$ref: '#/components/schemas/TransactionStatus'
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
ExecutionDate:
$ref: '#/components/schemas/TransactionExecutionDate'
Type:
$ref: '#/components/schemas/TransactionType'
Nature:
$ref: '#/components/schemas/TransactionNature'
CreditedWalletId:
type: string
description: The unique identifier of the credited wallet.
CreditedUserId:
$ref: '#/components/schemas/CreditedUserId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
PaymentType:
type: string
description: '**Returned values:** `KLARNA`
The payment type of the pay-in.'
ExecutionType:
type: string
description: '**Returned values:** `WEB`
The execution type of the pay-in.'
ReturnURL:
$ref: '#/components/schemas/ReturnURL_255'
RedirectURL:
type: string
description: 'The URL to which to redirect the user to complete the payment.
**Caution:** This variable URL is specific to each payment. You must rely on the returned URL in full (host, path, and queries) and not hardcode any part of it.'
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor'
Billing:
$ref: '#/components/schemas/Billing_DefaultsShippingUser_Response'
Shipping:
$ref: '#/components/schemas/Shipping_DefaultsBillingUser_Response'
LineItems:
type: array
items:
$ref: '#/components/schemas/KlarnaPayInResponseLineItemsItems'
description: Information about the items purchased in the transaction. The pay-in `DebitedFunds.Amount` must equal all `LineItems` objects' ((`UnitAmount` + `TaxAmount`) - `Discount`).
Country:
type: string
description: 'Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))
The country of residence of the user.'
Culture:
type: string
description: 'Format: Two-letter language code ([ISO 639-1 alpha-2](/api-reference/overview/data-formats))
The language in which the Klarna payment page is to be displayed. The `Culture` must match the `Country` to show the checkout page in the desired language. If not, or if `Culture` is not sent, EN is the language by default.'
Email:
type: string
description: 'Format: A valid email address
The user''s email address.'
Phone:
type: string
description: 'Format: International E.164 standard (preceded by plus sign and country code)
The user''s mobile phone number. If the phone matches the user''s Klarna account, their checkout experience involves one less step.'
PaymentMethod:
type: string
description: 'The payment option chosen by the user:
- Pay Now (Card) – Pay now by card.
- Pay Now (Direct Bank Transfer) – Pay now by bank wire.
- Pay Now (Direct Debit) – Pay now by direct debit.
- Pay Now (Klarna Bank Account) – Pay now from Klarna Bank Account (select regions only, e.g. Germany).
- Pay in 30 days (by card) – Pay within 30 days by card.
- Pay in 30 days – Pay within 30 days against an invoice (select regions only, e.g. Germany).
- Slice it (3 installments) – Pay in 3 installments.
- Slice it (Financing - X installments) – Pay via financing plan, where X is the number of monthly installments (6, 12, 24, or 36).
The options available to users depend on their region.
**Note:** This parameter is not returned unless the `Status` is `SUCCEEDED`.'
AdditionalData:
type: string
description: 'Format: Serialized JSON object
The extra merchant data required by Klarna for the transaction, as described in the <a href="https://mangopay.com/docs/concepts/payments/payment-methods/klarna" target="_blank">Klarna</a> guide.'
Reference:
type: string
description: The platform's order reference for the transaction.
description: 'A Klarna pay-in:
- `PaymentType` – `KLARNA`
- `ExecutionType` – `WEB`'
title: KlarnaPayInResponse
Tag:
type: string
description: 'Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.'
title: Tag
Billing_DefaultsShippingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address'
description: '**Default values:** `FirstName`, `LastName`, and `Address` information of the `Shipping` object if sent, otherwise of the `AuthorId` (if address values present).
Information about the billing address. '
title: Billing_DefaultsShippingUser_Response
CreateAKlarnaPayInRequestFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
required:
- Currency
- Amount
description: Information about the fees.
title: CreateAKlarnaPayInRequestFees
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
Error:
type: object
properties:
Message:
type: string
description: Description of the error.
Type:
type: string
description: 'The category of the error.
'
Id:
type: string
description: Unique identifier of the error instance, useful when contacting Mangopay for support.
Date:
type: number
format: double
description: Unix timestamp (UTC) of the date and time the error was triggered.
errors:
type:
- object
- 'null'
additionalProperties:
type: string
description: 'Object containing one or more field-level errors.
'
description: 'The error body typically returned by the Mangopay API for any non-2xx HTTP status code.
'
title: Error
ReturnURL_255:
type: string
description: 'Max. length: 255 characters
The URL to which the user is returned after the payment, whether the transaction is successful or not.'
title: ReturnURL_255
Id:
type: string
description: 'Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.'
title: Id
CreateAKlarnaPayInRequestBilling:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address_SubPropsRequired'
required:
- FirstName
- LastName
- Address
description: "Information about the billing address. \n\nThe `Billing.Address.Country` must be the same as the pay-in's `Country` parameter."
title: CreateAKlarnaPayInRequestBilling
CreateAKlarnaPayInRequestShipping:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address_SubPropsRequired'
required:
- FirstName
- LastName
- Address
description: 'Information about the end user''s shipping address.
The shipping address `AddressLine1` must be formatted:
- FR, UK, US: [Number][StreetName], for example: 33 Cavendish Square
- Rest of EU: [StreetName][Number], for example: De Ruijterkade 7
**Caution:** Failure to follow this formatting may result in an error.
If no shipping address is sent, Klarna considers it to be the same as the billing address.'
title: CreateAKlarnaPayInRequestShipping
ResultCode:
type: string
description: The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
title: ResultCode
CreateAKlarnaPayInRequest:
type: object
properties:
Tag:
$ref: '#/components/schemas/Tag'
AuthorId:
$ref: '#/components/schemas/AuthorId'
DebitedFunds:
$ref: '#/components/schemas/CreateAKlarnaPayInRequestDebitedFunds'
description: Information about the debited funds.
Fees:
$ref: '#/components/schemas/CreateAKlarnaPayInRequestFees'
description: Information about the fees.
CreditedWalletId:
type: string
description: The unique identifier of the credited wallet.
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorRequest'
ReturnURL:
$ref: '#/components/schemas/ReturnURL_255'
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor'
Billing:
$ref: '#/components/schemas/CreateAKlarnaPayInRequestBilling'
description: "Information about the billing address. \n\nThe `Billing.Address.Country` must be the same as the pay-in's `Country` parameter."
Shipping:
$ref: '#/components/schemas/CreateAKlarnaPayInRequestShipping'
description: 'Information about the end user''s shipping address.
The shipping address `AddressLine1` must be formatted:
- FR, UK, US: [Number][StreetName], for example: 33 Cavendish Square
- Rest of EU: [StreetName][Number], for example: De Ruijterkade 7
**Caution:** Failure to follow this formatting may result in an error.
If no shipping address is sent, Klarna considers it to be the same as the billing address.'
LineItems:
type: array
items:
$ref: '#/components/schemas/CreateAKlarnaPayInRequestLineItemsItems'
description: Information about the items purchased in the transaction. The pay-in `DebitedFunds.Amount` must equal all `LineItems` objects' ((`UnitAmount` + `TaxAmount`) - `Discount`).
Country:
type: string
description: 'Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))
The country of residence of the user.'
Culture:
type: string
description: 'Format: Two-letter language code ([ISO 639-1 alpha-2](/api-reference/overview/data-formats))
The language in which the Klarna payment page is to be displayed. The `Culture` must match the `Country` to show the checkout page in the desired language. If not, or if `Culture` is not sent, EN is the language by default.'
Email:
type: string
description: 'Format: A valid email address
The user''s email address.'
Phone:
type: string
description: 'Format: International E.164 standard (preceded by plus sign and country code)
The user''s mobile phone number. If the phone matches the user''s Klarna account, their checkout experience involves one less step.'
AdditionalData:
type: string
description: 'Format: Serialized JSON object
The extra merchant data required by Klarna for the transaction, as described in the <a href="https://mangopay.com/docs/concepts/payments/payment-methods/klarna" target="_blank">Klarna</a> guide.'
Reference:
type: string
description: The platform's order reference for the transaction.
ProfilingAttemptReference:
$ref: '#/components/schemas/ProfilingAttemptReference'
required:
- AuthorId
- DebitedFunds
- Fees
- CreditedWalletId
- ReturnURL
- Billing
- LineItems
- Country
- Email
- Reference
title: CreateAKlarnaPayInRequest
TransactionType:
type: string
description: '**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`
The type of the transaction.'
title: TransactionType
KlarnaPayInResponseCreditedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
title: KlarnaPayInResponseCreditedFunds
securitySchemes:
oauth2:
type: http
scheme: bearer
description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL."
x-provenance:
method: harvested
publisher: Mangopay
source: https://docs.mangopay.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)