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

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

Coopay payments follow an authorization–capture model and support:

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

1. Coopay Authorization First – Single Full Capture Later

The shopper selects Coopay 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 Coopay Push (No Redirect)
    autonumber

    participant Shopper
    participant MB as Merchant Backend
    participant Aera
    participant Coopay
    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 Coopay (no redirect)
    Note over Shopper,Aera: Shopper selects Coopay on Aera Hosted Checkout Page\nMerchant already knows shopper identity (no phone input step)
    Shopper->>Aera: Choose Coopay as payment method
    Aera->>Coopay: Initiate Coopay payment (shopper identifier)

    Coopay-->>Mobile: Push notification (approve payment)
    Shopper->>Mobile: Approve payment
    Mobile->>Coopay: Submit approval result

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

    %% 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": ["COOPAY"]  //Optional, only if restricted to Coopay
    }
  }
}

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": "COOPAY",
  "paymentScheme": "COOPAY"
}

Step 4 – Capture

POST /v1/{pspReference}/capture

No body → full capture.

2. Coopay 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

In this scenario multiple captures for a single authorization could be requested. This is indicated by setting splitShipment to true.

Session Configuration

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

However, since BankAxept ePayment only supports one single capture (partial or full) and a BankAxept ePayment card can be set as the preferred payment instrument in the Coopay wallet, Coopay Session Create requests with splitShipment set to true will be declined.

Validation Considerations

For Coopay payments to be available:

• Merchant must have an acquirer agreement for the relevant schemes supported by Coopay, i.e. Visa, Mastercard and BankAxept ePayment.
• Merchant must be se configured to accept Coopay