Migrate Klarna Payments Partners
Migrate a Partner's existing Klarna Payments setup onto Klarna's Management API with the migrate action, supplying their Klarna Payments Merchant Identifiers so the Partner Account is created with its history intact.
48 min read
Use the migrate
action to bring a Partner's existing Klarna Payments setup onto Klarna's Management API. Migration creates the Partner Account and its related resources from the data you submit, while linking the Partner's existing Klarna Payments Merchant Identifiers (MIDs) so their transaction history is preserved.
action to bring a Partner's existing Klarna Payments setup onto Klarna's Management API. Migration creates the Partner Account and its related resources from the data you submit, while linking the Partner's existing Klarna Payments Merchant Identifiers (MIDs) so their transaction history is preserved.Migration is the right choice only for Partners that already accept Klarna Payments:
- migrate — for Partners with an existing Klarna Payments setup. You supply their Klarna Payments MID(s), and the call overwrites the data held on each MID with the payload you send.
- onboard — for new Partners that don't accept Klarna Payments yet. See Prepare the onboarding payload.
Integration requirement
The migrate call overwrites the data held on each MID you declare with the contents of your payload. Make sure the payload is complete and correct before you run it — any data you omit is not carried over from their Klarna Payments setup.
call overwrites the data held on each MID you declare with the contents of your payload. Make sure the payload is complete and correct before you run it — any data you omit is not carried over from their Klarna Payments setup.The overwrite applies to the MID data only. Once the first migration succeeds, you can keep adding to the Partner Account on Klarna — see Migrate incrementally.
Before you build the migration payload, make sure you have:
- The Partner's existing Klarna Payments MID(s). Each MID must belong to the calling Acquiring Partner and be operational. See Which MIDs can be migrated.
- A pre-provisioned Payment Acquiring Account that can settle the Partner you're migrating — it must belong to the same Acquiring Partner and region as the MID, and carry the settlement configuration the MID is already linked to.
- The Payment Profile for the product. The Price Plan on the MID must match the one the Payment Profile references.
Recommended for integration
Klarna prepares each MID for migration ahead of your call so its Price Plan matches the Payment Profile you'll declare. Ask your Klarna contact to confirm that the MIDs you plan to migrate are prepared before you run the call.
Management API credentials required
You call migrate with your Klarna Management API credentials — the same ones you use to onboard new Partners. These are not the Klarna Payments credentials tied to the Partner Identifier (PID) that the Partner's existing setup uses. The Partner's Klarna Payments credentials and integration are unaffected by the migration.
with your Klarna Management API credentials — the same ones you use to onboard new Partners. These are not the Klarna Payments credentials tied to the Partner Identifier (PID) that the Partner's existing setup uses. The Partner's Klarna Payments credentials and integration are unaffected by the migration.The account structure, references, and data immutability rules, and how to select a Payment Acquiring Account or Payment Profile, all work exactly as they do for onboarding — this page covers only what's different for migration.
The migration request is not the same as the onboard request, but it reuses the same account structure for its shared fields — Partner Account details, Partner Business Entities, Brands, Store Groups, and Stores. For those shared fields, follow Prepare the onboarding payload.
What's specific to migration is inside each Payment Account: alongside the standard Payment Account fields, it declares the Klarna Payments
merchant_id to migrate and the payment_acquiring_account_id of the money corridor it settles through.One MID per Payment Account
Each Payment Account migrates one MID into one money corridor. To migrate several MIDs for the same Partner, declare one Payment Account per MID within the same request — up to 10 per request. If the Partner has more, migrate the rest in a follow-up call, as described in Migrate incrementally. Migrating more than one MID onto a single Payment Account isn't supported yet.
Sample request for a single corridor with a single MID:
Sample request
JSON
1
2
3
4
5
6
7
8
9
10
{
"partner_account_reference": "M123786123412",
"partner_account_name": "John Doe Stakehouse",
"partner_account_contact": {
"given_name": "John",
"family_name": "Doe",
"email": "john.doe@example.com",
"phone": "+18445527621"
},
"products": [Here you can find all required parameters for this operation, migrate.
.Run the migrate action from your backend with the payload you built.
action from your backend with the payload you built.Send an optional
Klarna-Idempotency-Key header so retries are safe.Recommended for integration
Sending a
Klarna-Idempotency-Key is recommended. Use a UUID (v4 or v7). The key is valid for at least 60 seconds:- An identical replay within the window returns the original response.
- A request with a different payload but the same key within the window returns a
422 Unprocessable EntitywithIDEMPOTENCY_KEY_MISMATCH. That points to a key you've reused by mistake — correct it before retrying. - After the window, a replay counts as a new request. Reference matching still stops anything Klarna has already stored from being migrated twice.
A key covers one logical request. A later incremental migration is a new logical request, so generate a new key for it instead of reusing the one from the first call.
On success, the response is the same shape as the onboarding response. Store the returned
partner_account_id for later API integrations. The state reflects setup progress — PARTIALLY_OPERATIONAL while some setup continues in Klarna's systems in the background, and OPERATIONAL once complete.Sample response:
Sample response
JSON
1
2
3
4
5
6
7
{
"partner_account_id": "krn:partner:global:account:live:LWT2XJSE",
"partner_account_reference": "M123786123412",
"partner_account_name": "Merchant ABC US",
"state": "PARTIALLY_OPERATIONAL",
"state_reason": "INITIAL_SETUP"
}Here you can find all required parameters for this operation, migrate.
.Subscribe to the
partner.account.state-change.operational webhook to know when the account becomes operational. Response handling and webhook subscription work the same as for onboarding — see Submit the onboarding request.The preset Payment Programs configured by the Payment Profile you declared become available on the migrated Partner Account automatically, with no further call from you. Optional Payment Programs stay optional: enable them on the migrated Partner Account as you would for any other account, by creating a Payment Program Enablement.
Each MID you declare must satisfy every rule below. If any check fails, the whole request is rejected — see Handle errors for the responses.
| Rule | Requirement |
|---|---|
| Ownership | The MID exists and belongs to the calling Acquiring Partner. |
| Not already migrated | The MID has not already been migrated or onboarded in this API. |
| Operational | The MID is not disabled. |
| Compatible acquiring account | The Payment Acquiring Account you declare can settle this Partner — it belongs to the same Acquiring Partner and region as the MID, and carries the settlement configuration the MID is linked to. |
| Compatible Price Plan | The Price Plan on the MID matches the Price Plan referenced by the Payment Profile you declare. |
A failed compatibility check returns a
400 VALIDATION_ERROR for merchant_id with the reason it was rejected. Declare a Payment Acquiring Account and Payment Profile that match the MID, or reach out to your Klarna contact if none of the ones available to you do.A MID can only be migrated onto a Payment Acquiring Account in its own region. The migration never changes a MID's region or settlement configuration, so the Payment Acquiring Account you declare has to match both.
If you hold Klarna Payments MIDs in a region where you don't have a Payment Acquiring Account, those MIDs can't be migrated yet — the call is rejected with the compatibility error in Handle errors. Reach out to your Klarna contact to confirm how to proceed for those regions.
Migration reuses the incremental onboarding concept, so the same rules apply when you run migrate more than once for the same Partner:
more than once for the same Partner:- Add-only. You can add new sub-entities, but modifying an existing sub-entity is rejected.
- Unique references and exact matches. New Payment Account references must be unique per Acquiring Partner. If the payload includes another existing resource, its fields must match what Klarna has stored.
- Any existing Partner Account can receive a MID. Calling migrate with the same
partner_account_referencemigrates any MIDs in the payload that Klarna hasn't stored yet into that Partner Account. The account doesn't need to have been created by an earlier migrate action — one created through onboard can receive a MID too. Send its existing partner_account_referencetogether with a new Payment Account that declares the MID. - Replays are safe. Resubmitting a payload that's already fully migrated returns success with the existing Partner Account, so retrying after a timeout won't migrate anything twice.
Once a Partner is migrated, resources that don't carry a MID follow the standard onboarding flow. Use the onboard action to create additional Brands, Store Groups, Stores, or Partner Business Entities on the migrated Partner Account. A Payment Account that brings across another MID goes through migrate instead.
action to create additional Brands, Store Groups, Stores, or Partner Business Entities on the migrated Partner Account. A Payment Account that brings across another MID goes through migrate instead.| Error | HTTP | Cause |
|---|---|---|
VALIDATION_ERROR | 400 | A MID is malformed, or the declared Payment Acquiring Account configuration is invalid. |
VALIDATION_ERROR | 400 | The declared Payment Acquiring Account can't settle this Partner — merchant_id identifies the rejected field, and the reason identifies a different Acquiring Partner, region, or settlement configuration. |
VALIDATION_ERROR | 400 | The Price Plan on the MID doesn't match the Price Plan referenced by the declared Payment Profile — merchant_id identifies the rejected field, and the reason identifies the Price Plan mismatch. |
RESOURCE_NOT_FOUND | 404 | A referenced resource can't be found for the Acquiring Partner — a MID that doesn't exist or doesn't belong to you, or a Payment Acquiring Account or Payment Profile that can't be found. |
RESOURCE_CONFLICT | 409 | A MID is already migrated or onboarded in this API. |
RESOURCE_CONFLICT | 409 | A newly-added Payment Account reference already exists for the Acquiring Partner. |
RESOURCE_CONFLICT | 409 | A reference in the payload reuses an existing reference with values that differ from what Klarna has stored. |
MIGRATION_NOT_ALLOWED | 409 | A MID can't be migrated in its current state — for example, it's disabled on Klarna Payments. |
IDEMPOTENCY_KEY_MISMATCH | 422 | The same Klarna-Idempotency-Key was replayed within the validity window with a different payload. |
A
MIGRATION_NOT_ALLOWED response won't clear on its own, so don't retry the call unchanged. Contact your Klarna representative to resolve the MID's state, then resubmit the same payload.Jump to section...