Documentation
Documentation
Express Checkout

1Introduction

Express Checkout lets customers pay directly from a product or cart page using wallet buttons (for example PayPal, Apple Pay, or Google Pay), without going through a separate checkout form.

2Integration Steps

The integration has five logical steps:

Step Part Required? What it means for the merchant

1

Create session (POST /api/v2.0/express-checkout/session/create)

Yes

Create one session per checkout attempt and store the returned identifiers.

2

Render wallet widget (iframe with sessionToken)

Yes

Show the wallet UI to the customer.

3

Shipping callback (merchantShippingCallbackUrl)

Conditional

Required only when shippable items exist and shipping options must be calculated dynamically.

4

Return to shop and create order (GET merchantRedirectUrl)

Yes

After customer approval, the flow returns to your shop. Create the order in this step. Optionally fetch session details (GET /api/v2.0/express-checkout/session) to validate or enrich the order with final address, shipping option, and totals.

5

Process session (POST /api/v2.0/express-checkout/session/process)

Yes

Call this after return to merchantRedirectUrl, then redirect the browser to the response redirectUrl.

Redirect terms:

  • merchantRedirectUrl is where the flow returns the customer to your shop.

  • redirectUrl is returned by /express-checkout/session/process and is the next URL your shop must redirect the customer to.

3Flow

Express Checkout Integration Flow

3.11. Create an Express Checkout Session

  • Method: POST

  • URL: /api/v2.0/express-checkout/session/create

  • Authentication: HMAC token

For the full list of fields and their descriptions, see API Client. Request model: IExpressCheckoutSession.ICreate. Response model: ExpressCheckoutSessionCreateResponse.

{
  "currency": "CHF",
  "merchantRedirectUrl": "https://your-shop.com/checkout/complete?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "merchantShippingCallbackUrl": "https://your-shop.com/api/shipping-options?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "paymentMethodConfigurationId": 12345,
  "lineItems": [
    {
      "uniqueId": "item-1",
      "sku": "SKU-001",
      "name": "Product Name",
      "type": "PRODUCT",
      "quantity": 1,
      "amountIncludingTax": 42.00,
      "shippingRequired": true,
      "currency": "CHF",
      "taxes": []
    }
  ]
}

In this example, sessionUuid=550e8400-e29b-41d4-a716-446655440000 is a merchant-generated correlation value. The shop must map sessionUuid to the returned sessionId.

The response contains:

  • sessionId — the ID of the created session

  • sessionToken — security token needed for processing

Implementation notes:

  • Required in practice: include order-defining data (currency, lineItems, merchantRedirectUrl).

  • Conditionally required: provide merchantShippingCallbackUrl when the wallet must request shipping options.

  • Optional: paymentMethodConfigurationId can be provided to target a specific payment method configuration. If not provided, the first available configured payment method configuration is used.

  • Required for reliable correlation: generate your own sessionUuid, append it to merchantRedirectUrl and merchantShippingCallbackUrl, and store a mapping sessionUuid <→ sessionId.

  • Store identifiers appropriately: persist sessionId for later processing. Keep sessionToken available until widget rendering is completed (persistent storage is optional).

3.22. Render the Wallet Widget

Embed the wallet iframe in your page using the widget URL built with the sessionToken. The widget handles address selection, shipping option display, and payment approval.

Minimal embed example:

<script src="https://<scope-base-path>/assets/payment/express-checkout-handler.js"></script>

<div id="express-checkout-container"></div>

<script>
  window.ExpressCheckoutHandler.load('express-checkout-container', sessionToken);
</script>

The handler derives the target scope from the sessionToken and builds the widget endpoint as /s/{spaceId}/express-checkout/widget/{sessionToken}. Using a scope-based script URL remains recommended, but root /assets/payment/express-checkout-handler.js also works as long as the sessionToken is passed unchanged.

Implementation notes:

  • Required: render the widget with the containerId and the sessionToken from session creation.

3.33. Process the Payment

After wallet approval and return to your merchantRedirectUrl, call the processing endpoint to create the transaction and authorize the payment.

  • Method: POST

  • URL: /api/v2.0/express-checkout/session/process

  • Authentication: HMAC token (same as all REST API calls)

For the full list of fields and their descriptions, see API Client. Request model: IExpressCheckoutSessionProcessRequest. Response model: ExpressCheckoutSessionProcessResponse.

{
  "sessionId": 123456,
  "orderId": "ORDER-789",
  // Optional. If omitted, the default URLs configured in the portal are used.
  "successUrl": "https://your-shop.com/checkout/success",
  "failureUrl": "https://your-shop.com/checkout/failure"
}

Implementation notes:

  • Required: call this endpoint after approval and after the customer is redirected back from the portal to your shop.

  • Required: provide sessionId and an idempotent orderId to make retries safe.

  • Required: redirect the browser to the URL returned in the response.

  • Optional: successUrl and failureUrl can be omitted. If omitted, the default URLs configured in the portal are used.

  • Optional (recommended): fetch session details before processing to validate final amount, address, and selected shipping option.

  • Recommended: treat webhooks as the source of truth for final asynchronous status (AUTHORIZED / FAILED), while browser redirects drive customer navigation.

The response contains a redirect target URL. Redirect the customer there to continue 3DS (if needed) and complete the flow.

4Optional: Read Session Details Before Processing

You can retrieve the approved Express Checkout session before processing. This is useful to create or validate the shop order based on the final customer selections.

  • Method: GET

  • URL: /api/v2.0/express-checkout/session

  • Authentication: HMAC token

For the full list of fields and their descriptions, see API Client.

Typical usage:

  1. Resolve your internal checkout reference to the stored sessionId

  2. Fetch the session details

  3. Build or validate your order from the returned address, selected shipping option, and totals

  4. Call /express-checkout/session/process

5Optional: Shipping Options Provider API

If your products require shipping, you must implement a callback endpoint that wallee calls to fetch shipping options when the customer changes their address. The URL of this endpoint is provided per session via the merchantShippingCallbackUrl field in the create request.

The callback contract uses the following three models (for this callback, these models might not be listed under /doc/api/web-service):

  • IExpressCheckoutShippingOptionRequest

    • Required: countryCode, currency, language, expressCheckoutId, spaceId, requestId

    • Optional: state, street, city, postalCode

  • IExpressCheckoutShippingOptionsResponse

    • shippingOptions: list of IExpressCheckoutShippingOption entries (return at least one on success, empty list on error). For the full list of fields and their descriptions, see IExpressCheckoutShippingOption.

    • error: null on success, or an IExpressCheckoutShippingOptionsClientError object on business error

  • IExpressCheckoutShippingOptionsClientError

    • Fields: error (short type), message (human-readable explanation), timestamp (optional time string)

5.1Endpoint Specification

  • Method: POST

  • URL: Your configured callback URL

  • Content-Type: application/json

5.2Request

Wallee sends the following fields in IExpressCheckoutShippingOptionRequest:

Field Type Required? Notes

expressCheckoutId

Long

Yes

Identifier of the Express Checkout session.

spaceId

String

Yes

Merchant space identifier.

requestId

String

Yes

Correlation ID for tracing.

countryCode

String

Yes

Country code (ISO-3166 alpha-2).

currency

String

Yes

Currency code (ISO-4217).

language

String

Yes

Language code (ISO-639).

state

String

No

State or province code.

street

String

No

Street address.

city

String

No

City name.

postalCode

String

No

Postal or ZIP code.

 
{
  "expressCheckoutId": 123456,
  "spaceId": "84",
  "requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
  "countryCode": "CH",
  "currency": "CHF",
  "language": "en",
  "state": "ZH",
  "street": "Example Street 5",
  "city": "Winterthur",
  "postalCode": "8400"
}

5.3Response (returned by your shop to wallee)

Return a JSON object with shipping options or an error. Your shop endpoint must return IExpressCheckoutShippingOptionsResponse to wallee as the HTTP response body.

Response contract:

  • Success path: return one or more shippingOptions and set error to null.

  • Error path: return an empty shippingOptions array and provide a populated error object.

  • Do not use non-200 HTTP codes for business errors: keep HTTP 200 and communicate errors in the body.

  • Use non-200 HTTP codes only for technical failures: for example invalid payload format, authentication failure, or server-side outage.

5.3.1Shipping Option Fields

Field Type Required? Notes

id

String

Yes

Unique identifier of the shipping option.

label

String

Yes

Display name shown to the customer.

description

String

No

Optional descriptive text.

amountIncludingTax

Decimal

Yes

Total shipping amount including taxes.

taxes

Array

No

Tax lines with title and rate (percentage). Can be empty.

currency

String

Yes

ISO-4217 currency code. Must match the session currency.

5.3.2Error Fields

Field Type Required? Notes

error

String

Yes

Short error type identifier (for example INVALID_ADDRESS, SERVICE_UNAVAILABLE).

message

String

Yes

Human-readable error description.

timestamp

String

No

Timestamp when the error occurred.

5.3.3Success 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standard Shipping",
      "description": "Delivery in 3-5 business days",
      "amountIncludingTax": 9.99,
      "taxes": [
        { "title": "VAT", "rate": 7.70 }
      ],
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Express Shipping",
      "description": "Delivery in 1-2 business days",
      "amountIncludingTax": 19.99,
      "taxes": [
        { "title": "VAT", "rate": 7.70 }
      ],
      "currency": "CHF"
    }
  ],
  "error": null
}

5.3.4Error 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "The provided shipping address is not valid for shipping calculations",
    "timestamp": "2025-10-10T12:00:00Z"
  }
}

6Supported Wallets

Wallet Status Notes

Bogus Pay

Available

For testing and development only.

PayPal

In progress

—

Apple Pay

Planned

—

Google Pay

Planned

—

7Testing with Bogus Pay

For testing, use Bogus Pay.

It provides mock addresses, test cards, and approval flows (including 3DS simulation).

Staging 2.199.2