Documentation
Documentation
Express Checkout

1Express Checkout Shipping Options Provider API Integration

The Express Checkout Shipping Options Provider API allows merchants to provide dynamic shipping options during the Express Checkout flow only. When customers change their shipping address or when shipping options need to be calculated in the Express Checkout process, wallee will call the merchant’s Shipping Options Provider API to retrieve available shipping options.

Important

This API is specifically designed for the Express Checkout flow and should not be used for regular checkout processes.

1.1Shipping Options Provider API Callback URL Configuration

Before implementing the Shipping Options Provider API endpoint, merchants must configure the callback URL in their space settings.

1.1.1Configure Callback URL

Go to Settings > General > Space to configure the callback URL.

The callback URL should point to your Shipping Options Provider endpoint that will handle shipping option requests.

1.2Shipping Options Provider Callback Endpoint

Merchants must implement a REST endpoint that wallee can call to fetch shipping options based on the customer’s shipping address.

1.2.1Endpoint Specification

  • Method: POST

  • URL: The URL configured in the space settings (see above)

  • Content-Type: application/json

1.2.2Request Format

The payload that wallee sends to the merchant endpoint follows the IExpressCheckoutShippingOptionRequest structure and exposes the following flattened fields:

Field Type Required? Notes

expressCheckoutId

Long

Yes

Identifier of the Express Checkout session.

spaceId

String

Yes

Merchant space identifier (for multitenancy).

requestId

String

Yes

Correlation ID used to trace requests per session.

countryCode

String

Yes

Country code (ISO-3166 alpha-2).

currency

String

Yes

Currency code for the transaction (ISO-4217).

language

String

Yes

Language code used for localization (ISO-639).

state

String

No

State or province code (ISO-3166-2 where available).

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"
}

Key points:

  • expressCheckoutId, spaceId, requestId, countryCode, currency, and language are always present.

  • No additional order data is transmitted; merchants should derive any required context themselves.

1.2.3Response Format

The response must be a unified JSON object containing either a list of shipping options or an error.

1.2.3.1Success Response 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standard Shipping",
      "description": "Delivery in 3-5 business days",
      "amount": 9.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Express Shipping",
      "description": "Delivery in 1-2 business days",
      "amount": 19.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    }
  ],
  "error": null
}

1.2.3.2Error Response 

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

1.2.4Field Descriptions

  • shippingOptions: A list of available shipping options. Can be empty if no options are available.

  • error: An error object if something went wrong. null on success.

The shippingOptions object has the following fields:

  • id: Unique identifier for the shipping option (required)

  • label: Display name for the shipping option (required)

  • description: Optional description of the shipping option

  • amount: Shipping cost excluding tax (required, BigDecimal)

  • taxAmount: Tax amount for shipping (required, BigDecimal)

  • currency: ISO-4217 currency code for the shipping cost (required)

The error object has the following fields:

  • error: A short string identifying the error type (e.g., "INVALID_ADDRESS").

  • message: A human-readable message explaining the error.

  • timestamp: The timestamp of when the error occurred.

1.3Error Handling

The Shipping Options Provider API should always return an HTTP 200 OK status code. Errors should be communicated in the error field of the response body.

1.3.1Invalid Address 

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

1.3.2No Options Available

Return an empty shippingOptions list when no shipping options are available for the given address:

{
  "shippingOptions": [],
  "error": null
}

1.3.3Service Unavailable 

{
  "shippingOptions": [],
  "error": {
    "error": "SERVICE_UNAVAILABLE",
    "message": "Shipping calculation service is temporarily unavailable",
    "timestamp": "2023-10-10T12:00:00Z"
  }
}

1.4Implementation Guidelines

1.4.1Address Validation

  • Validate that the shipping address contains all required fields for shipping calculations

  • Check if the address is within supported shipping regions

  • Return appropriate error responses for invalid or unsupported addresses

1.4.2Shipping Calculation Logic

  • Calculate shipping costs based on:

    • Shipping address location

    • Order weight/dimensions (derived from line items)

    • Order value

    • Shipping speed/service level

  • Consider tax calculations for shipping costs

  • Apply merchant-specific rules (minimum order values, free shipping thresholds, etc.)

1.4.3Performance Considerations

  • Respond within 30 seconds to avoid timeouts

  • Cache shipping calculations when possible

  • Implement efficient algorithms for weight/dimension calculations

1.4.4Security

  • Validate that requests are coming from trusted wallee IPs

  • Log requests for audit purposes

1.5Testing

1.5.1Test Cases

  • Valid address with multiple shipping options

  • Valid address with single shipping option

  • Invalid address (missing required fields)

  • Unsupported country/region

  • Empty order (no line items)

  • Heavy order requiring special shipping

  • Free shipping threshold reached

1.5.2Sample Test Request 

curl -X POST https://your-shop.com/api/shipping-options \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "givenName": "John",
      "familyName": "Doe",
      "street": "Main St 123",
      "city": "Zurich",
      "postcode": "8000",
      "country": "CH"
    },
    "currency": "CHF"
  }'

1.5.3Sample Success Response 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Standard Shipping",
      "description": "Delivery in 3-5 business days",
      "amount": 9.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Express Shipping",
      "description": "Delivery in 1-2 business days",
      "amount": 19.99,
      "taxAmount": 0.00,
      "currency": "CHF"
    }
  ],
  "error": null
}

1.5.4Sample Error Response 

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

1.6Error Handling Best Practices

  • Always return an HTTP 200 OK status code.

  • Provide descriptive error messages in the error field of the response.

  • Log errors for debugging purposes.

  • Implement fallback behavior for when the service is unavailable.

1.7Support

For questions about implementing the Shipping Options Provider API callback, please refer to the wallee merchant documentation or contact wallee support.