Disputes migration to V4

Klarna is introducing Disputes API V4, which adds multi-phase review, an appeal workflow, and richer dispute outcomes. To allow a seamless migration with no service disruption, V1, V2, V3 and V4 operate in parallel during the migration window.

Two key dates drive the migration:

• Your V4 onboarding timestamp — the dividing line between dispute frameworks. Disputes opened before it are FRAMEWORK_2020 (legacy); disputes opened after it are FRAMEWORK_2026. Assignment is automatic and permanent. The framework is always readable from configuration.base_framework.
• November 1, 2026 — a second cutoff within FRAMEWORK_2026 when the 30-day review window, the appeal workflow, and the ON_DISPUTE_OPEN hold policy activate.

Two access models to remember:

• REST is cross-version: Once onboarded to V4, every dispute (any framework) is readable and actionable on every API version.
• Webhooks are framework-scoped: V1/V2/V3 subscriptions deliver FRAMEWORK_2020 events only; V4 subscriptions deliver FRAMEWORK_2026 events only. Both must run in parallel until all FRAMEWORK_2020 disputes have closed.

FRAMEWORK_2020 (legacy)

Applies to disputes opened before your V4 onboarding timestamp. Follows the legacy dispute rules and lifecycle. No changes are made to disputes already under this framework.

{
  "configuration": {
    "base_framework": "FRAMEWORK_2020",
    "options": { "hold_policy": "NONE" }
  }
}

FRAMEWORK_2026

Applies to disputes opened after your V4 onboarding timestamp. Follows the FRAMEWORK_2026 lifecycle with multi-phase review, new settlement transaction types, and a configurable hold policy.

Default configuration from onboarding:

{
  "configuration": {
    "base_framework": "FRAMEWORK_2026",
    "options": { "hold_policy": "NONE" }
  }
}

Phased feature rollout — November 1, 2026. Not all FRAMEWORK_2026 features activate at onboarding. The features below only apply to disputes opened on or after Nov 1, 2026:

Implications:

• The appeal flow will not trigger for any dispute until Nov 1, 2026 — do not treat it as a day-one requirement.
• SLA monitoring must account for the 60-day review window for all FRAMEWORK_2026 disputes opened before that date.
• New settlement transaction types (CHARGEBACK_REVERSAL, APPEAL_FEE) must be integrated before Nov 1, 2026 — see Settlement transaction types.

hold_policy reference

FRAMEWORK_2020 lifecycle (V1/V2/V3)

Total maximum duration: ~95 days.

In V1/V2/V3 this is reflected in investigation_status:

FRAMEWORK_2026 lifecycle (V4)

FRAMEWORK_2026 has two sub-phases depending on whether the dispute opened before or on/after November 1, 2026.

Disputes opened before Nov 1, 2026 (transitional):

Disputes opened on or after Nov 1, 2026 (full):

Key differences from FRAMEWORK_2020:

• "Open" and "Evidence Requested" are combined into a single state (INITIATED) — the dispute opens with an immediate evidence request, giving up to 21 days from day one.
• Review period is 30 days (down from 60), from Nov 1, 2026.
• Two new phases: PRE_ARBITRATION (preliminary decision, partner can appeal) and ARBITRATION (final binding review).

In V4 this is reflected in state:

Within INITIATED and REPRESENTMENT, a nested representment.state tracks the evidence request status:

V2 → V4 state mapping

REST: cross-version access

Once onboarded to V4, every REST operation is available on every API version, regardless of dispute framework. You can shift workflows dispute-by-dispute or team-by-team at your own pace — for example, accessing FRAMEWORK_2020 disputes via V4, or FRAMEWORK_2026 disputes via your existing V2 integration.

Webhooks: framework-scoped delivery

Webhook event delivery does not cross framework boundaries:

The migration follows five sequential steps. The diagram below summarises the end-to-end flow:

Complete every item below before calling the V4 onboarding endpoint. Once onboarded, disputes opened after the timestamp immediately use FRAMEWORK_2026.

Dispute routing:

• Dispute management system reads configuration.base_framework and routes to the correct processing logic.
• State machine updated to handle the V4 5-state model: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CLOSED.
• Code handles unknown dispute_outcome_detailed values gracefully (open enum — new values may be added).

Evidence submission:

• Evidence submission updated to use free-text additional_information (max 5000 chars) instead of structured requested_fields.
• Attachment handling updated to use KRN-based IDs and include descriptions.

Authentication:

• V4 API key credentials obtained.
• V4 authentication tested (HTTP Basic auth with API key, not V2 client credentials).

Webhooks (if applicable):

• HMAC-SHA256 signature verification implemented in your webhook handler.
• Webhook handler routes events based on base_framework.
• V1/V2/V3 webhook subscription confirmed active and will remain active during migration.

No settlement changes are required before V4 onboarding. With hold_policy: NONE (the FRAMEWORK_2026 default), no funds are held when a dispute opens, so settlement behaviour is unchanged from the legacy behavior:

• Dispute closes in merchant's favor → no settlement entry (nothing was held).
• Dispute closes against the merchant → CREDIT appears in the settlement report.
• FEE continues to appear as it does today.

Two new transaction types activate on November 1, 2026 when hold_policy: ON_DISPUTE_OPEN and the appeal workflow go live. These must be integrated before that date — see Settlement transaction types in the API reference for the full table.

Call the V4 self-onboarding endpoint. This records the timestamp that divides FRAMEWORK_2020 from FRAMEWORK_2026.

POST /v4/payment/disputes/merchants/{merchant_id}/enroll

After this call:

• Your MID is active on V4.
• Disputes opened before this timestamp → FRAMEWORK_2020.
• Disputes opened after this timestamp → FRAMEWORK_2026 with the default config (hold_policy: NONE).
• All FRAMEWORK_2020 disputes are immediately accessible via V4 — you can view and respond to them using either V1/V2/V3 or V4 from this point forward.

Subscribe to V4 webhooks to receive events for FRAMEWORK_2026 disputes.

Rules:

• Your existing V1/V2/V3 webhook subscription stays active — it continues delivering events with base_framework = FRAMEWORK_2020.
• Your V4 webhook subscription delivers FRAMEWORK_2026 events only.
• Disputes opened before onboarding will never appear on the V4 subscription.
• Disputes opened after onboarding will never appear on the V1/V2/V3 subscription.
• Run both subscriptions in parallel for the entire migration period.

For the full event catalogue, payload routing logic, and deadline-extension handling, see Webhook events and routing in the API reference.

With both integrations active, incrementally migrate dispute workflows to V4 while FRAMEWORK_2020 disputes continue via your existing integration.

Recommended validation sequence:

1. For the first 1–2 weeks after onboarding, process FRAMEWORK_2026 disputes exclusively via V4.
2. Optionally cross-access: use V4 to view and respond to a subset of FRAMEWORK_2020 disputes to confirm compatibility.
3. Validate that dispute_outcome_detailed values are handled correctly — this is an open enum; unknown values must not crash your system.
4. Confirm settlement files include the new transaction types for FRAMEWORK_2026 disputes.
5. If using webhooks: confirm FRAMEWORK_2020 events arrive on the V1/V2/V3 subscription and FRAMEWORK_2026 events on the V4 subscription.
6. Monitor PRE_ARBITRATION events — if your workflow requires challenging preliminary decisions, implement the appeal flow before this occurs in production.

Once all FRAMEWORK_2020 disputes have reached CLOSED:

1. Cancel the V1/V2/V3 webhook subscription.
2. Retire your V1/V2/V3 API integration.
3. All future disputes will be FRAMEWORK_2026.

V4 onboarding does not modify or break your existing V1/V2/V3 integration. At any point you can:

• Stop sending requests to V4 — your V1/V2/V3 integration continues to work without change.
• FRAMEWORK_2020 disputes are unaffected by V4 onboarding.

The only irreversible effect is framework assignment: disputes opened after your onboarding timestamp cannot be moved back to FRAMEWORK_2020.

The evidence submission model changed significantly between V2 and V4.

V2 — structured field responses

V2 required merchants to respond to explicit field requests with structured enum values:

// POST /disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses
{
  "requested_fields": {
    "tracking_id": "ABC123",
    "shipping_date": "2024-01-15",
    "shipping_carrier": "DHL",
    "delivered_with_proof": "yes",
    "goods_returned": "yes_in_full"
  },
  "comment": "All requested information provided.",
  "attachments": [1, 2, 3]
}

V4 — free-text with attachments

V4 replaces structured fields with a flexible free-text model:

// POST /v4/payment/disputes/{payment_dispute_id}/represent
{
  "additional_information": "Shipment was delivered on 2024-01-20 with signature confirmation. Tracking: XYZ789.",
  "attachments": [
    {
      "payment_dispute_attachment_id": "krn:payment:eu1:dispute:123:attachment:1",
      "description": "Signed delivery confirmation"
    },
    {
      "payment_dispute_attachment_id": "krn:payment:eu1:dispute:123:attachment:2",
      "description": "Courier tracking history screenshot"
    }

Key differences:

• additional_information max length: 5000 characters.
• No structured field mapping — include all relevant information in the text or as attachments.
• Attachments referenced by KRN identifier, not numeric ID.
• Attachment descriptions are optional but recommended.
• Include tracking numbers, dates, and carrier information in additional_information; supporting documents as attachments.

V4 introduces an appeal flow for the PRE_ARBITRATION state. If Klarna issues a preliminary decision and you wish to challenge it:

POST /v4/payment/disputes/{payment_dispute_id}/appeal

PRE_ARBITRATION and the appeal workflow are only available for FRAMEWORK_2026 disputes opened on or after November 1, 2026. For disputes opened before that date, the dispute goes directly from REPRESENTMENT to CLOSED — no appeal is possible. This endpoint has no V2 equivalent.

Event catalogue

Routing by framework

Use base_framework in the webhook payload to route processing:

if payload.configuration.base_framework == "FRAMEWORK_2020":
    route to V1/V2/V3 processing flow
elif payload.configuration.base_framework == "FRAMEWORK_2026":
    route to V4 processing flow

Webhook events are not duplicated across subscriptions — each subscription receives only its framework's events, so no deduplication is needed.

Handling deadline extensions

V4 introduces deadline extensions via the payment.dispute.updated.representment-deadline-extended event. When received:

• Update the stored representment.expires_at value in your system.
• Re-queue any deadline-based automations using the new expiry.

CREDIT and FEE are unchanged — they exist today under FRAMEWORK_2020 and continue to work identically under FRAMEWORK_2026.

Before November 1, 2026 (with hold_policy: NONE):

• Dispute closes in merchant's favor → no settlement entry (nothing was held, nothing to return).
• Dispute closes against the merchant → CREDIT in settlement report, same as the legacy behavior.
• FEE continues to appear as it does today.
• Disputes transition directly from REPRESENTMENT to CLOSED.

Two new transaction types activate on November 1, 2026, when hold_policy: ON_DISPUTE_OPEN and the appeal workflow go live:

V2:

{
  "error_code": "INCOMPATIBLE_DISPUTE_STATE",
  "error_message": "Cannot perform operation in current dispute state"
}

V4:

{
  "error_id": "abc123",
  "error_type": "BAD_VALUE",
  "error_code": "INVALID_FIELD_VALUE",
  "error_message": "Human-readable error message",
  "validation_errors": [
    {
      "field": "representment.additional_information",
      "message": "Field must be between 0 and 5000 characters"
    }
  ]
}

V4 errors include a unique error_id for tracing, an error_type for programmatic handling, and a validation_errors array for field-level detail.

V4 uses API key credentials with HTTP Basic Authentication — different from V2's OAuth2 client credentials flow. Ensure your V4 requests use the correct authentication scheme.

V4 introduces dispute_outcome_detailed in the CLOSED state with 40+ possible values (e.g. partner_provided_valid_shipping_details, no_proof_of_delivery, customer_cancelled_dispute). New values may be added in the future. Your code must not crash or reject unknown values — handle them gracefully and log them for review.