> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/custom-connector.md).

# Custom connector

Custom connectors let The Wallet Crew integrate with systems that do not have a native connector. They are useful when a Brand or partner needs to fetch external data, react to wallet lifecycle events, or route transactional emails through an internal delivery stack.

## Custom connectors for tenant-specific integrations

A custom connector is not a separate product module. It is a project-specific integration layer implemented with runtime hooks exposed by The Wallet Crew.

In practice:

1. The source system keeps ownership of business data.
2. The connector script resolves and maps the data needed by wallet passes.
3. The Wallet Crew generates and updates Apple Wallet and Google Wallet payloads.

This keeps the wallet layer aligned with your existing systems without forcing a full native connector.

## What is needed to design a new connector

Before implementation, define these inputs:

| Required input                                                | Why it matters                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------- |
| Source system and owner                                       | Clarifies which team controls business rules and data quality |
| Stable identifiers (customerId, membershipId, ticketId, etc.) | Links wallet passes to source records over time               |
| Trigger model (pull, push, lifecycle hooks)                   | Defines when data is fetched and when updates are propagated  |
| API/event contract                                            | Defines authentication, payload shape, and error handling     |
| Operational ownership                                         | Clarifies who monitors integration failures and retries       |

If these inputs are unclear, align them first before writing scripts.

<details>

<summary><strong>Real-world examples</strong></summary>

* A Brand enriches a loyalty pass with points, tier, or profile data from a CRM.
* A team synchronizes pass installation status with a marketing, analytics, or BI platform.
* A partner keeps The Wallet Crew email rendering, but sends through its own gateway.

</details>

## What this section covers

This section groups the custom connector patterns that are used most often in delivery projects.

### Pass lifecycle hooks

Use this pattern when an external system must react to wallet installation changes.

Typical use cases include CRM synchronization, install-based segmentation, onboarding journeys, and uninstall tracking.

* [Pass installation and uninstallation hooks](/connectors/custom-connector/installation-changed-extensibility.md)

### Script-based email delivery

Use this pattern when The Wallet Crew should still build the email content, but the final send must be handled by a provider or relay controlled outside The Wallet Crew.

This is useful for internal gateways, unsupported ESPs, or environments with strict delivery governance.

* [EmailSender extensibility](/connectors/custom-connector/emailsender-extensibility.md)

### Runtime scripting

Some custom connectors also need broader runtime scripts to enrich pass data or register custom provider logic.

This section focuses on the connector entry points used most often in Connect projects. For runtime registration and implementation details, see [Developer custom connectors guide](https://github.com/TheWalletCrew/docs/tree/main/developers/guides/integration-guides/custom-connectors.md).

## When to use a custom connector

Use a custom connector when the integration needs are specific enough that a built-in connector would not fit cleanly.

Use a standard connector when one already exists. A standard connector can also be scoped by The Wallet Crew and the platform partner when it can support multiple Brands.

Use a custom connector when tenant scripting must call a private API, use an internal relay, or react to pass lifecycle events.

## Responsibilities split

| Topic                            | Customer / partner                                 | The Wallet Crew                                  |
| -------------------------------- | -------------------------------------------------- | ------------------------------------------------ |
| External system access           | Provides APIs, credentials, and business ownership | Provides runtime execution context               |
| Data mapping rules               | Defines semantic mapping from source fields        | Applies mapped data to wallet payload generation |
| Lifecycle reactions              | Decides what to do on install/uninstall            | Emits lifecycle hooks and events                 |
| Email delivery (script provider) | Sends emails through selected relay/provider       | Builds templates and calls script runtime        |

## FAQ

<details>

<summary><strong>When should a built-in connector be used instead?</strong></summary>

Use a built-in connector when The Wallet Crew already supports the target platform and the expected workflow matches the project needs. Use a custom connector when the integration depends on private APIs, internal relays, or runtime-specific logic.

</details>

<details>

<summary><strong>Is this the right place for install and uninstall synchronization?</strong></summary>

Yes. For wallet installation lifecycle events, start with [Pass installation and uninstallation hooks](/connectors/custom-connector/installation-changed-extensibility.md).

</details>

<details>

<summary><strong>Is this the right place for a custom email gateway?</strong></summary>

Yes. For script-based transactional email sending, use [EmailSender extensibility](/connectors/custom-connector/emailsender-extensibility.md).

</details>

<details>

<summary><strong>Where is the generic custom connector scripting model documented?</strong></summary>

This page focuses on the connector entry points exposed in the **Connect** section. Broader runtime scripting patterns are documented separately.

</details>

<details>

<summary><strong>Can an unlisted platform become a standard connector?</strong></summary>

Yes. The Wallet Crew and the platform partner can jointly scope a built-in connector when it can support multiple Brands. For tenant-specific integrations, use a custom connector with tenant scripting and APIs.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thewalletcrew.io/connectors/custom-connector.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.