OnKustomExternalPaymentMethods hook

Kustom Checkout can present external payment methods (EPM) — payment options not built into Kustom, such as PayPal. When the customer selects one, Kustom collects the address and then redirects the browser to a merchant-owned URL that owns the entire purchase flow. Kustom does not create or track an order for external payments and sends no postback.

The Kustom app fires the custom hook OnKustomExternalPaymentMethods while building the Kustom order in the checkout ingress. Merchant rules listen to it and return the external payment methods to add for the current cart and channel.

Address Handoff

The Kustom app wraps each effect's redirect_url in a Hantera-owned handoff ingress before sending the list to Kustom. When the customer picks an EPM, Kustom redirects to the handoff, which:

1. Fetches the Kustom order to read the address Kustom captured.
2. Applies that address (and the billing address / VAT id) to the cart.
3. 302s the browser to the merchant's original redirect_url.

This means the EPM app (e.g. PayPal) sees a fully addressed cart from the moment its own start ingress runs — it does not need to collect or pass the address itself. The wrapping is transparent to the merchant rule: the redirect_url you emit is the URL the customer ultimately lands on.

If the address handoff fails (Kustom order cannot be fetched, or the cart rejects the address commands), the handoff returns an error response instead of forwarding. An unaddressed cart cannot be fulfilled, so dead-ending here is preferable to a downstream order failure.

When It Fires

Once per Kustom order creation, from the checkout ingress, before the order is sent to Kustom. The effects returned by listeners are added to the Kustom order's external_payment_methods array. If no listener returns a method, the array is omitted.

Hook Input

{
  hook: 'OnKustomExternalPaymentMethods'
  cartId: uuid
  channelKey: text
  currencyCode: text
  orderTotal: number
  systemHost: text
  checkoutUrl: text
  confirmationUrl: text
}

Field	Notes
cartId	The cart being checked out.
channelKey	Channel the cart belongs to — use this to scope which channels offer which methods.
currencyCode	Order currency.
orderTotal	Order total (in major units).
systemHost	The tenant host, for building absolute redirect URLs.
checkoutUrl	The storefront checkout URL (used as the EPM cancel/return-to-checkout target).
confirmationUrl	The storefront confirmation URL the external provider should land on after completion.

Emitting a Method

Listeners emit a custom effect with type = 'externalPaymentMethod'. The Kustom app maps these to KCO external_payment_methods entries.

Field	Required	Notes
effect	yes	Must be 'custom'.
type	yes	Must be 'externalPaymentMethod'.
name	yes	Method name. Must match a Kustom-supported name (e.g. PayPal), case-sensitive.
redirect_url	yes	HTTPS page that owns purchase completion.
image_url	no	HTTPS, exactly 69×24px.
description	no	Up to 500 chars; Markdown links allowed.
fee	no	Optional fee (minor units) added to the order.

Example: Offer PayPal on selected channels

import 'iterators'

param input: {
  hook: 'OnKustomExternalPaymentMethods'
  cartId: uuid
  channelKey: text
  currencyCode: text
  orderTotal: number
  systemHost: text
  checkoutUrl: text
  confirmationUrl: text
}

let paypalChannels = ['DE']

let isPaypalChannel =
  paypalChannels
  where c => c == input.channelKey
  count > 0

from isPaypalChannel match
  true |> [{
    effect = 'custom'
    type = 'externalPaymentMethod'
    name = 'PayPal'
    redirect_url = $'https://{input.systemHost}/ingress/paypal/start?cartId={input.cartId}&confirmationUrl={input.confirmationUrl}&checkoutUrl={input.checkoutUrl}'
  }]
  |> []

The redirect_url points at the PayPal app's start ingress, which owns the rest of the flow.

See Also

• PayPal app
• custom effect
• Kustom Commerce Integration