Express Docs v0.1.0

---

Express Docs / ExpressButtonsConfig

Interface: ExpressButtonsConfig

Defined in: src/types.ts:1514

Top-level configuration object passed to ExpressButtons().

Remarks

Combines the list of provider button configurations with lifecycle callbacks. The SDK renders all configured providers in parallel via Promise.allSettled.

The target environment (sandbox / production) is determined at build time — use the corresponding SDK build artifact rather than a config flag.

Example

const config: ExpressButtonsConfig = {
  providers: [
    {
      providerProtocolType: 'PayPal',
      paymentMethodType: 'PayPalExpress',
      container: '#paypal-container',
      style: { color: 'gold', shape: 'rect' },
      options: { intent: 'capture', currencyCode: 'USD' },
    },
  ],
  onClick: async (identity) => {
    const resp = await fetch('/api/create-order', { method: 'POST' });
    const data = await resp.json();
    return data.checkoutData; // base64-encoded payload from the server
  },
  onCancel: (identity) => { console.log('Cancelled', identity); },
  onError: (error) => { console.error(error); },
};

Extends

• CallbackHandlers

Properties

disableTelemetry?

optional disableTelemetry?: boolean

Defined in: src/types.ts:1524

When true, disables all telemetry collection. Defaults to false (telemetry enabled).

Default Value

false

---

onCancel?

optional onCancel?: (identity) => void

Defined in: src/types.ts:1444

Called when the shopper cancels the payment flow (e.g. closes the payment popup without completing). Optional — if omitted, cancellations are still tracked in telemetry but no integrator logic runs.

Parameters

identity

ProviderIdentity

Identifies which provider was cancelled.

Returns

void

Remarks

Recommended actions: restore any reserved inventory, show a user-friendly "payment was cancelled" message, and allow the user to try again.

In addition to firing onCancel in the browser, the collana pay backend sends an asynchronous server-to-server cancel callback to your backend so order state stays in sync even if the browser is closed.

Inherited from

CallbackHandlers.onCancel

---

onClick

onClick: (identity, options?) => Promise<string>

Defined in: src/types.ts:1428

Called when the shopper clicks a payment button.

Parameters

identity

ProviderIdentity

Identifies which provider button was clicked ({ providerProtocolType, paymentMethodType }).

options?

Record<string, unknown>

The provider-specific options object as configured (e.g. intent, currencyCode, totalAmount). Shape varies by provider.

Returns

Promise<string>

A promise resolving to the raw base64-encoded checkoutData string from your backend. Do not decode or parse it — return it as-is.

Remarks

This is the most important callback. It connects the SDK to your backend:

1. The SDK fires onClick with the provider identity and its configured options.
2. You send these to your backend to create an order via the CollanaPay API.
3. Your backend responds with a checkoutData string (base64-encoded).
4. You return that string — the SDK decodes it internally and extracts the fields needed to drive the provider flow (e.g. id for the PayPal order ID, debugId for telemetry correlation, returnUrl for post-approval redirects).

If onClick throws or returns a rejected promise, the payment flow is aborted and onError will fire.

See the Backend API docs for the expected request and response shapes when creating an order server-side.

Example

onClick: async (identity, options) => {
  const resp = await fetch('/your-backend/create-transaction', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ provider: identity, options }),
  });
  if (!resp.ok) throw new Error('Order creation failed');
  const data = await resp.json();
  return data.checkoutData;
}

Inherited from

CallbackHandlers.onClick

---

onError?

optional onError?: (identity, error) => void

Defined in: src/types.ts:1462

Called when an error occurs during the payment flow. Optional — if omitted, errors are still tracked in telemetry but no integrator logic runs.

Parameters

identity

ProviderIdentity

Identifies which provider encountered the error ({ providerProtocolType, paymentMethodType }).

error

PaymentError

Structured error object with code and message.

Returns

void

Remarks

Errors can originate from provider SDK failures, network errors, or when onClick rejects. Provider rendering uses Promise.allSettled, so one provider's failure does not prevent other providers from rendering. Each failure triggers a separate onError call.

Recommended actions: log the error for monitoring, show a user-friendly error message, and allow the user to retry.

Inherited from

CallbackHandlers.onError

---

providers

providers: ProviderButtonConfig<ProviderKey>[]

Defined in: src/types.ts:1516

One or more provider button configurations to render.