This section describes Vipps payment flow using the Aera Hosted Checkout Page.

Vipps scenarios start by creating a checkout session and redirecting (or embedding) the shopper to the returned checkoutUrl.

Vipps payments follow an authorization–capture model and support:

• Authorization only first. later full capture
• Immediate capture
• Multiple partial captures (split shipment)

1. Vipps Authorization First – Single Full Capture Later

The shopper selects Vipps and authorizes the payment on the Aera Hosted Checkout Page.
The merchant later performs a single full capture.

Sequence Diagram

sequenceDiagram
    title Checkout – Hosted Checkout with Vipps Redirect
    autonumber

    participant Shopper
    participant MB as Merchant Backend
    participant Aera
    participant Vipps
    participant Mobile as Shopper Mobile App

    %% Create Checkout Session
    Note over Shopper,Aera: Create Checkout Session
    Shopper->>MB: Initiate checkout
    MB->>Aera: POST /v1/session/payment/create
    Aera->>Aera: Validate request
    Aera-->>MB: sessionInfo (pspReference, checkoutUrl)
    MB-->>Shopper: Redirect to checkoutUrl

    %% Select Vipps and redirect out
    Note over Shopper,Aera: Shopper selects Vipps on Aera Hosted Checkout Page
    Shopper->>Aera: Choose Vipps as payment method
    Aera-->>Shopper: Redirect to Vipps page (enter phone number)

    Shopper->>Vipps: Enter phone number
    Vipps-->>Mobile: Push notification (approve payment)

    Shopper->>Mobile: Approve / Reject payment
    Mobile->>Vipps: Submit approval result

    %% Vipps callback and redirect back
    Vipps-->>Aera: Payment result callback (success / failed)
    Aera-->>Shopper: Redirect to merchant return URL\n(success / failed / cancel)

    %% 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
    alt Status API
        MB->>Aera: GET /v1/{pspReference}/status
        Aera-->>MB: Payment status + operations
    end

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

Step 1 – Create Session

POST /v1/session/payment/create

{
  "header": {
    "merchantId": "MER100000",
    "idempotency-key": "UUID v7"
  },
  "body": {
    "merchantInfo": {
      "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"
      }
    },
    "paymentMethodInfo": {
      "paymentMethodWhitelist": ["VIPPS"] 
//this is an optional data. In case you do not specify it, the checkout will show all available payment methods according to your agreement. When only Vipps is specified, the page will show only Vipps
    }
  }
}

Step 2 – Session Created Response

{
  "responseInfo": {
    "responseCode": 0,
    "responseText": "Success"
  },
  "sessionInfo": {
    "pspReference": "UUID v7 generated by Aera",
    "checkoutUrl": "https://checkout.aera.com/<sessionId>"
  }
}

Redirect the shopper to checkoutUrl and wait for Webhook.

Step 3 – Webhook (Session Completed)

{
  "eventType": "CHECKOUT_SESSION_COMPLETED",
  "status": "0",
  "pspReference": "UUIDv7 from Create response",
  "merchantReference": "12344333",
  "paymentMethod": "VIPPS",
  "paymentScheme": "VIPPS"
}

Step 4 – Capture

POST /v1/{pspReference}/capture

No body → full capture.

2. Vipps with immediate Capture (Authorization + Capture)

In this scenario, authorization and capture occur in a single step. When creating the Checkout session, you set immediateCapture to true such that a separate Capture is not required.

Request Configuration

"transactionData": {
  "merchantReference": "12344333",
  "immediateCapture": true,
  "amountDetails": {
    "amount": 10000,
    "currency": "NOK"
  }
}

The status response will include both:

• AUTHORIZATION
• CAPTURE

If capture fails, the transaction is reversed.

3. Split Shipment – Multiple Partial Captures

This scenario supports multiple captures for a single authorization. In this case, you set splitShipment to true.

Session Configuration

"transactionData": {
  "merchantReference": "12344333",
  "immediateCapture": false,
  "splitShipment": true,
  "amountDetails": {
    "amount": 10000,
    "currency": "NOK"
  }
}

Partial Capture Example

POST /v1/{pspReference}/capture

{
  "amountDetails": {
    "amount": 5000,
    "currency": "NOK"
  }
}

Additional captures may be performed until the full amount is captured.

Validation Considerations

For Vipps payments to be available:

• Merchant must have a Vipps agreement and Vipps configured