This section describes common card payment flows using the Aera Hosted Checkout Page.

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

Card payments follow an authorization–capture model and support:

Authorization only
Immediate capture
Single full capture
Multiple partial captures (split shipment)
Card verification (zero-amount authorization)
Optional card storage (Credentials on File)
Initial standing instruction for subsequent recurring payments

1. Card Authorization – Single Full Capture

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

Sequence Diagram

sequenceDiagram
    title Checkout – Standard Hosted Checkout
    autonumber

    participant Shopper
    participant MB as Merchant Backend
    participant Aera

    %% 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

    Note over Shopper,Aera: Shopper completes payment on Aera Hosted Checkout Page
    Shopper-->>MB: Redirect (success / cancel / error)

    %% 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": ["CARD"]
    }
  }
}

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

Step 4 – Capture

POST /v1/{pspReference}/capture

No body → full capture.

2. Card Authorization – Store Card (Credentials on File)

This scenario allows the shopper to store the card for future use in addition to completing the payment. The stored card can be used for a faster checkout next time where the shopper does not need to enter the card details again.

Sequence Diagram

sequenceDiagram
    title Checkout – Store Card (Credentials on File)
    autonumber

    participant Shopper
    participant MB as Merchant Backend
    participant Aera

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

    Note over Shopper,Aera: Shopper completes payment on Aera Hosted Checkout Page\nand selects "Store card"
    Aera->>Aera: Create stored credential entry (Credentials on File)

    Shopper-->>MB: Redirect (success / cancel / error)

    %% 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 + STORED_CREDENTIALS operation
    end

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

Additional Request Parameter

"paymentInstrumentsProfileData": {
  "merchantShopperId": "LOYAL-70018882",
  "storePaymentInstrument": "OPTIONAL"
}

If card storage is enabled for the merchant, the checkout page presents a “store card” option. If set to MANDATED, the option is prechecked and gray, i.e. storing the card is mandated and the shopper is not allowed to de-check.

The status response includes an additional operation:

{
  "type": "STORED_CREDENTIALS",
  "status": "COMPLETED",
  "details": {
    "merchantShopperId": "LOYAL-70018882",
    "pspShopperId": "UUID",
    "paymentInstrumentReference": "UUID"
  }
}

3. Card Authorization – Stored Cards Only

This scenario restricts the checkout to previously stored cards, meaning the shopper has to complete payment with a stored card. There is not option to manually enter card details.

Typical Use Cases

Restricting checkout to previously stored cards is typically used in:

Returning customer flows where the shopper is already authenticated and has a stored payment method.
Subscription or recurring billing models where payment must be made using an approved card on file.
Loyalty or membership programs where purchases are tied to a known customer account.
One-click checkout experiences designed to minimize friction and improve conversion.

Sequence Diagram

sequenceDiagram
    title Checkout – Pay with Stored Card Only
    autonumber

    participant Shopper
    participant MB as Merchant Backend
    participant Aera

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

    Note over Shopper,Aera: Shopper selects from previously stored cards only.\nManual card entry is not available.

    Shopper-->>MB: Redirect (success / cancel / error)

    %% Notify Merchant
    Note over MB,Aera: Notify Merchant
    alt Webhook
        Aera-->>MB: CHECKOUT_SESSION_COMPLETED\n(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\n(Full amount)
    Aera-->>MB: Capture response

Additional Request Parameter

{
  "paymentInstrumentsProfileData": {
  "merchantShopperId": "LOYAL-70018882",
  "allowStoredInstrumentsOnly": true
}

The checkout page displays only stored cards.

4. 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.

5. 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.

6. Card Verification (Zero-Amount Authorization)

This scenario verifies the card validity without charging the shopper.

Request Configuration

{
  "transactionData": {
    "merchantReference": "12344333",
    "immediateCapture": false,
    "storePaymentInstrument": true,
    "amountDetails": {
      "amount": 0,
      "currency": "NOK"
    }
  }
}

This performs a zero-amount authorization with mandated storage of the card. Implicitly this forces explicit authentication.

7. "One-click" payment using a stored card

This scenario is using the Authorize endpoint for intiating a payment referring to a prior stored card and without showing the checkout UI.

If the amount is lower than the low-value exemption limit (currently 300 NOK, 30 EUR) the payment is initiated as a low-value exemption payment. If approved there is no shopper interaction. The checkoutUrlin the response is then empty.

If low-value exemption is "soft-declined" by the issuer (authentication required) or the amount is higher than the low-value limit, authentication is required and the checkoutUrlin the response need to be rendered by the merchant. The authenticaton may be frictionless or require explicit shopper authentication.

Request Configuration

{
  "transactionData": {
    "merchantReference": "12344333",
    "immediateCapture": true,
    "merchantShopperId": "LOYAL-70018882",
    "paymentInstrumentReference": "....",
    "amountDetails": {
      "amount": 100,
      "currency": "NOK"
    }
  }
}

8. Storing card for subsequent recurring payments

This scenario describes the initial standing instruction for subsequent recurring payments using Create MIT endpoint .

Request Configuration

{
  "transactionData": {
    "merchantReference": "12344333",
    "immediateCapture": true,
    "recurringProcessingInfo": {
      "recurringModel": 0,
      "recurringFrequency": 28
    },
    "amountDetails": {
      "amount": 200,
      "currency": "NOK"
    }
  }
}

This sets up an initial standing instruction for a monthly standing order / subscription with variable amount. The initial payment (first term) is 200 NOK, but this amount is not linked to the future recurring payments.

The merchant must store the recurringReference from the response of the Status request and use it for the subsequent recurring payments.

9. Merchant-initiated recurring payment

This scenario is using the Authorize MIT endpoint for intiaing recurring payments. It requires a prior approval by the shopper and storing a card for subsequent recurring payments.

Request Configuration

{
  "transactionData": {
    "merchantReference": "12344333",
    "immediateCapture": true,
    "merchantShopperId": "LOYAL-70018882",
    "paymentInstrumentReference": "....",
    "amountDetails": {
      "amount": 100,
      "currency": "NOK"
    }
  }
}

Validation Considerations

For card payments to be available:

Merchant must have at least one acquirer configured
At least one card scheme must be enabled
Acquirer must support the configured service, MCC, and operation type

Availability and behavior may vary depending on:

Acquirer capabilities
Scheme rules
Merchant configuration

Scenario 1: Card Payments with Aera´s Hosted Checkout Page

1. Card Authorization – Single Full Capture

Sequence Diagram

Step 1 – Create Session

Step 2 – Session Created Response

Step 3 – Webhook (Session Completed)

Step 4 – Capture

2. Card Authorization – Store Card (Credentials on File)

Sequence Diagram

Additional Request Parameter

3. Card Authorization – Stored Cards Only

Typical Use Cases

Sequence Diagram

Additional Request Parameter

4. Immediate Capture (Authorization + Capture)

Request Configuration

5. Split Shipment – Multiple Partial Captures

Session Configuration

Partial Capture Example

6. Card Verification (Zero-Amount Authorization)

Request Configuration

7. "One-click" payment using a stored card

Request Configuration

8. Storing card for subsequent recurring payments

Request Configuration

9. Merchant-initiated recurring payment

Request Configuration

Validation Considerations

What’s Next