Express Docs v0.1.0

---

Express Docs / CallbackHandlers

Interface: CallbackHandlers

Defined in: src/types.ts:1387

Callback functions that the integrator must supply to handle payment lifecycle events.

Remarks

These callbacks are invoked by the SDK at various stages of the payment flow. Each provider wraps them with telemetry before calling.

Example

const callbacks: CallbackHandlers = {
  onClick: async (identity, options) => {
    const resp = await fetch('/api/orders', {
      method: 'POST',
      body: JSON.stringify({ provider: identity, options }),
    });
    const data = await resp.json();
    // Return the raw base64-encoded checkoutData string from the server.
    return data.checkoutData;
  },
  onCancel: (identity) => {
    console.log('Payment cancelled', identity);
  },
  onError: (identity, error) => {
    console.error(`[${error.code}] ${error.message}`);
  },
};

Extended by

• ExpressButtonsConfig

Properties

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.

---

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

---

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.