Walley Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Walley Checkout Adapter integrates Walley Checkout with Norce Checkout. This page focuses on the unique technical details and configuration for Walley.

Supported payment methods and other features: Features Overview

Configuration in Norce Admin

The adapter is configured using the following unique details obtained from Walley:

Store ID Configuration

Configure Store IDs for each country and customer type combination:

Feature Toggles

Redirect URLs

Configure the URLs that Walley uses for callbacks and redirects:

Styling Options

Customize the appearance of the Walley Checkout iframe:

Mapping Options

Configure how order data is mapped to Walley:

Localization Options

Configure localized text for discounts and vouchers:

Frontend Integration Requirements

Required Event: Customer Update

Before implementing the Walley Checkout customer update event handler, ensure you have:

• The Walley Checkout script loaded on your page
• A valid Norce Checkout order ID and payment ID
• Your Norce merchant and channel identifiers
• A valid Norce authentication token (Bearer token)

Listen for the walleyCheckoutCustomerUpdated event from Walley and call the customer update endpoint:

// Initialize Walley event listener (after the Walley checkout script loads)
window.addEventListener('walleyCheckoutCustomerUpdated', async function(data) {
  const orderId = /* your order ID */;
  const paymentId = /* your payment ID */;
  const merchant = /* your merchant ID */;
  const channel = /* your channel ID */;
  const token = /* your authentication token */;

  await fetch(`/api/checkout/v1/callback/orders/${orderId}/payments/${paymentId}/customer-update`, {
    method: 'POST',
    headers: {
      'x-merchant': merchant,
      'x-channel': channel,
      'Authorization': 'Bearer ' + token
    }
  });
});

Endpoint:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/customer-update

This endpoint updates the Norce order with the latest customer information from Walley, including email address (critical for discount validation), billing address, delivery address, and loyalty membership data.

Failure to implement this event handler will result in:

• Email-based discounts not being validated correctly
• Customer information not being synchronized with Norce until purchase completion
• Potential order validation failures when the order is locked during payment processing

Required Event: Shipping Option Update

When using Walley's delivery module (useDeliveryModule enabled), listen for shipping option changes to keep the Norce order synchronized:

window.addEventListener('walleyCheckoutShippingOptionUpdated', async function(data) {
  const orderId = /* your order ID */;
  const paymentId = /* your payment ID */;
  const merchant = /* your merchant ID */;
  const channel = /* your channel ID */;
  const token = /* your authentication token */;

  await fetch(`/api/checkout/v1/callback/orders/${orderId}/payments/${paymentId}/shipping-option-update`, {
    method: 'POST',
    headers: {
      'x-merchant': merchant,
      'x-channel': channel,
      'Authorization': 'Bearer ' + token
    }
  });
});

Endpoint:

POST /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-option-update

This endpoint updates the Norce order with the selected shipping option from Walley, including shipping method, shipping cost, and delivery address.

Failure to implement this event handler will result in:

• Shipping costs not being synchronized with Norce until purchase completion
• Order totals being incorrect due to mismatched shipping prices
• Potential order validation failures when the order is locked during payment processing
• Customer experiencing unexpected price differences between Walley and the order confirmation

Walley Checkout UI Locking During Payment Processing

When the customer initiates payment (clicks the purchase button), your checkout frontend should enter a locked state where:

• All form inputs are disabled
• Shipping options cannot be changed
• Cart modifications are prevented
• A loading indicator is displayed

This prevents race conditions where the customer might modify the order while payment is being processed, which can cause validation failures or unexpected order states.

For more details on Walley client-side events, see the Walley Checkout Client Events documentation.

Loyalty Integration

The Walley adapter automatically captures loyalty membership data from Walley orders. No configuration is required to enable this feature.

When a completed Walley order includes a loyaltyMembership on the customer object, the adapter reads this value and stores it as a Norce customer attribute with the key walleyCustomerLoyaltyMembership.

Unlike other features such as useDeliveryModule or useUpsell, there is no feature toggle for loyalty — the capture happens passively whenever Walley provides membership data on the order.

Walley API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Walley uses the following external API environments:

Idempotency and Retries

Walley may send multiple notification callbacks for the same event. The adapter handles idempotency to ensure that duplicate notifications do not result in duplicate order processing. For detailed information about Walley's retry behavior, see the Walley Checkout documentation on Idempotency and retries.

Troubleshooting (Walley Specific)

In addition to the generic troubleshooting steps:

• Review the order status directly in Walley's merchant portal.
• If Capture fails, verify the Norce order is in the reserved state and that the Walley order status allows capture.
• If Refund fails, ensure the order has been captured and has not already been returned.
• Use the refresh call to update available payment actions:

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/refresh
Host: {slug}.api-se.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Links and References

• Walley Checkout Adapter (Business Overview)
• Walley Checkout Adapter OpenAPI Specification
• Walley Checkout Documentation (External)
• Walley Checkout API Reference (External)