Custom connector

Extend The Wallet Crew with tenant-side scripts to call external services or implement runtime-specific integration logic.

Custom connectors extend The Wallet Crew with tenant-side scripts. They are useful when pass data must be enriched from an external system or when custom logic must run when a pass is installed or uninstalled.

This pattern keeps the integration inside the tenant runtime. It avoids exposing connector logic in client-side code and makes external calls easier to control.

Real-world examples

• A Brand enriches a loyalty pass with points and tier data from an external CRM.

• A partner fills a pass with profile attributes coming from a proprietary API.

• A team synchronizes pass installation status with a marketing or analytics platform.

Requirements

To create a script, open Settings → Advanced → Advanced Configuration. This section contains the tenant configuration files.

Script files are stored under /server/script/....

customProvider is only an example name. You can replace every customProvider occurrence with the connector name that should be registered or you can keep it.

Create the script file

In the file explorer, create a file such as /server/script/customProvider.js.

If the folder or file does not exist yet, create it first. To create a folder from the file explorer, enter the folder name followed by /.

Register the connector

Once the script file exists, add the connector registration:

export default function(context) {
  context.register('runtime.scriptable.customerProvider.customProvider', {
    Fill: fill
  });
  context.register('runtime.wallet.passUpdater', {
    OnPassInstalled: onPassInstalled,
    OnPassUninstalled: onPassUninstalled
  });
}

Fill function

The Fill function is the entry point used to retrieve and inject external data into the pass lifecycle.

In practice, this function receives the current pass context, calls the required external services, and returns or applies the data needed by the connector. The exact implementation depends on the external system being connected.

The runtime contract for Fill is available in the Fill function reference.

Example implementation

This example reads the external identifiers that are added when a pass is created, calls an external API, and maps the response back into the entity.

async function fill(entity) {
  const externalId = entity["id.externalId"];
  if (!externalId) {
    return false;
  }

  try {
    const res = await fetch("https://example.com/api/wallet", {
      Method: "GET",
      Headers: {
        "Content-Type": "application/json",
        "X-API-KEY": API_KEY,
      }
    });

    const item = JSON.parse(res.ResponseText)[0];

    entity.eventName = item?.eventName ?? `event ${externalId}`;
    entity.external_last_name = item?.lastName ?? null;
    entity.external_first_name = item?.firstName ?? null;
    entity.external_image_url = item?.imageUrl ?? null;
    entity.external_logo = item?.logo ?? null;
    entity.external_color = item?.color ?? null;
    entity.external_background_color = item?.backgroundColor ?? null;

    return true;
  } catch (e) {
    entity.external_error = `An error occurred while calling the external API: ${e}`;
    return true;
  }
}

What this registration does

The script registers two runtime entry points. Each one serves a different purpose.

runtime.scriptable.customerProvider.customProvider

This registration exposes a function named Fill. The Fill function is used to populate passes with external data.

This is the place to call external APIs and enrich pass data with information coming from partner systems, CRM platforms, loyalty engines, or any other backend connected to the project.

runtime.wallet.passUpdater

This registration exposes two lifecycle hooks:

• OnPassInstalled

• OnPassUninstalled

These hooks are triggered when a pass is installed or uninstalled. They make it possible to run connector logic at the exact moment the wallet lifecycle changes.

Typical uses include synchronizing installation status, starting a welcome flow, or stopping reminder communications once the pass is already installed.

The runtime contract for these hooks is available in the OnPassInstalled and OnPassUninstalled reference.

For the full install and uninstall hook behavior, see Pass installation and uninstallation hooks.

FAQ

Does the script file need to be named customProvider.js?

No. The filename can follow any naming convention used by the project. What matters is the runtime registration key used inside the script.

Can customProvider be replaced with another connector name?

Yes. Replace customProvider with the connector name that should be exposed by the runtime registration.

When should runtime.wallet.passUpdater be registered?

Register it when the integration must react to pass installation or uninstallation events. If only pass enrichment is needed, the customer provider registration may be enough.