Scenario 4: Embed Aera´s Hosted Payment Form in Your Checkout

This section describes how to integrate Aera Checkout using ui.mode == EMBED, including:

• Card payments
• Authentication flows (3DS / BankID) which may require breakout flows
• Payment-method breakout flows (e.g., Vipps, Walley)

The embedded model allows you to render Aera’s hosted checkout inside your own checkout page while safely handling flows that require top-level redirect or app-switch.

Refer to Integration Options for user experience.

Overview

With ui.mode = EMBED:

1. Your backend creates a checkout session.
2. Your frontend renders Aera’s hosted checkout in an <iframe>.
3. The iframe communicates with your page via postMessage.
4. If authentication or payment method requires it, Aera instructs you to break out of the iframe.
5. After completion, Aera redirects the browser back to your configured return URL.
6. You confirm the final status via webhook and/or session status API.

Sequence Diagram

sequenceDiagram
    title Checkout – Embedded Aera Checkout
    autonumber

    participant Shopper
    participant MF as Merchant Frontend (Parent Page)
    participant MB as Merchant Backend
    participant Aera
    participant Iframe as Aera Checkout (Iframe)
    participant EXT as External Auth / Method (3DS, Vipps, Walley)

    %% Create Session
    Note over Shopper,Aera: Create Checkout Session (ui.mode = EMBED)
    Shopper->>MF: Open checkout
    MF->>MB: Create payment session
    MB->>Aera: POST /checkout-sessions
    Aera-->>MB: Return iframeUrl
    MB-->>MF: Return iframeUrl

    %% Render Embedded Checkout
    Note over MF,Iframe: Render Embedded Checkout
    MF->>Iframe: Load iframe (iframeUrl)
    Shopper->>Iframe: Select method / Enter details / Confirm

    alt No external step required
        Iframe->>Aera: Process payment
        Aera-->>Iframe: Payment completed
        Iframe-->>MF: postMessage (completed)

    else Authentication required (3DS / BankID)
        Iframe->>Aera: Process payment
        Aera-->>Iframe: Authentication required
        Iframe-->>MF: postMessage (requires_breakout, redirectUrl)

        MF-->>Shopper: Redirect top-level to redirectUrl
        Shopper->>EXT: Complete authentication
        EXT->>Aera: Authentication result
        Aera-->>Shopper: Redirect back to merchant return URL

    else Payment method requires redirect (Vipps / Walley)
        Iframe-->>MF: postMessage (requires_breakout, redirectUrl)

        MF-->>Shopper: Redirect top-level to redirectUrl
        Shopper->>EXT: Complete payment flow
        EXT->>Aera: Payment result
        Aera-->>Shopper: Redirect back to merchant return URL
    end

    %% Notify Merchant
    Note over MB,Aera: Notify Merchant
    alt Webhook
        Aera-->>MB: CHECKOUT_SESSION_COMPLETED (pspReference)
        MB->>Aera: Acknowledge
    end

    %% Merchant Fetches Status
    Note over MB,Aera: Merchant Fetches Status
    MB->>Aera: GET /v1/{pspReference}/status
    Aera-->>MB: Payment status

    %% Capture by Merchant
    Note over MB,Aera: Capture by Merchant
    MB->>Aera: POST /v1/{pspReference}/capture
    Aera-->>MB: Capture response

1. Create Checkout Session

Example Request

When you want to embed Aera´s Checkout Form, start the create session with the ui.mode==EMBED and provide your origin.

{
  "header": {
    "merchantId": "MER100000",
    "idempotency-key": "UUID v7"
  },
  "body": {
    "merchantInfo": {
      "ui": {
        "mode": "EMBED",
        "origin": "https://merchant.example"
      },
      "successRedirectUrl": "https://frontend.merchant.com/success",
      "cancelRedirectUrl": "https://frontend.merchant.com/cancel",
      "errorRedirectUrl": "https://frontend.merchant.com/error",
      "webhookUrl": "https://backend.merchant.com"
    },
    "transactionData": {
      "merchantReference": "12344333",
      "immediateCapture": false,
      "amountDetails": {
        "amount": 10000,
        "currency": "NOK"
      }
    },
  }
}

Example Response

{
  "sessionInfo": {
    "pspReference": "018f7a2e-8f5c-7a9b-b123-123456789abc",
    "checkoutUrl": "https://checkout.aera.com/session/abc123",
    "ui": {
      "mode": "EMBED",
      "integration": {
        "type": "IFRAME",
        "iframeUrl": "https://checkout.aera.com/session/abc123",
        "events": {
          "transport": "POST_MESSAGE",
          "pspOrigin": "https://checkout.aera.com"
        }
      }
    },
    "capabilities": {
      "embedSupported": true,
      "breakoutMayBeRequired": true
    }
  }
}

2. Render the Checkout in an Iframe (Frontend)

Use the returned iframeUrl to render the form in your checkout page.

3. Listen for Checkout Events

Aera Checkout communicates using postMessage.

Security Requirement

Always validate:

• event.origin matches pspOrigin
• sessionId matches the expected session

4. Breakout Scenarios

Some flows cannot complete inside an iframe. In these cases, Aera emits:

aera.checkout.requires_breakout

You must redirect the top-level browser window.

4.1 Card Authentication (3DS / BankID)

If Strong Customer Authentication is required:

{
  "type": "aera.checkout.requires_breakout",
  "sessionId": "018f7a2e-8f5c-7a9b-b123-123456789abc",
  "reason": "AUTHENTICATION_REQUIRED",
  "subReason": "3DS_CHALLENGE",
  "paymentMethod": "CARD",
  "redirectUrl": "https://checkout.aera.com/auth/3ds/start?token=..."
}

Common causes:

• 3DS challenge
• BankID app-switch
• Issuer-mandated redirect

4.2 Payment Method Breakout (e.g. Vipps, Walley, Klarna)

Some payment methods may require:

• Top-level redirect
• Mobile app-switch
• Hosted KYC/identity flow and contract acceptance (Walley)

Example event:

{
  "type": "aera.checkout.requires_breakout",
  "sessionId": "018f7a2e-8f5c-7a9b-b123-123456789abc",
  "reason": "PAYMENT_METHOD_REQUIRES_REDIRECT",
  "paymentMethod": "VIPPS",
  "redirectUrl": "https://checkout.aera.com/redirect/vipps/start?token=..."
}

5. After Breakout: Return Handling

After completing authentication or payment:

Aera redirects the browser to one of:

• successRedirectUrl
• cancelRedirectUrl
• errorRedirectUrl

Important

Treat the return page as a continuation step.

Do not rely solely on frontend signals but also confirm the payment status by receiving the Webhook or send Get Status API to Aera.

6. Confirm Final Payment Status

Always confirm final state using:

• Webhook notification (recommended)
• Or Get status API

Key Integration Principles

• Not all authentication flows can run inside an iframe.
• Not all payment methods can complete inside an iframe.
• Always validate event.origin.
• Always confirm payment status server-side.
• Use breakout handling for 3DS, BankID, Vipps, and Walley flows.

With this model, you maintain an embedded checkout experience while safely handling authentication and redirect-based payment methods.