> 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/developers-guides/scripting/endpoints/apple-pass-resolver.md).

# Apple pass resolver

Recover an Apple Wallet pass that a device knows but The Wallet Crew does not, typically after a platform migration, with runtime.wallet.applePassResolver.

When a brand moves its Apple Wallet passes to The Wallet Crew from another platform, the passes already installed on customers' iPhones keep their serial numbers and authentication tokens. The first time such a device contacts The Wallet Crew about one of these passes, The Wallet Crew does not know the serial number. The Apple pass resolver lets a tenant script check that serial number and token against a trusted source, such as an export of the previous platform or the brand's own customer database, and tell The Wallet Crew which pass it is. The Wallet Crew then creates the pass with the same serial number and token, and the device keeps receiving updates as if nothing had changed. This page is the reference for `runtime.wallet.applePassResolver`.

The resolver is only meant for that recovery. It is not a way to create passes on demand, and it never runs for Google Wallet.

<details>

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

* After a migration, a loyalty program keeps the passes already in its members' wallets: the resolver looks each serial number up in the export of the previous platform and returns the member's customer id.
* A ticketing integration recovers the tickets issued before the switch from the ticketing system, which knows each ticket's serial number and token.

</details>

## Registration

The key is `runtime.wallet.applePassResolver`. Registering it is enough: no configuration file refers to it. Only **one** registration is allowed per tenant: when two are registered, every recovery fails.

```js
export default function (context) {
  context.register('runtime.wallet.applePassResolver', {
    ResolveMissingPass: async (request) => null
  });
}
```

## When it runs

The resolver runs when an Apple device registers a pass for updates (the call Apple Wallet makes when a pass is added, or when it re-registers it) and all of these hold:

* no pass of the tenant has that serial number;
* the request carries an Apple authentication token;
* the request carries a push token.

Before calling the script, The Wallet Crew checks the request itself: the serial number must be 5 to 50 letters, digits, underscores or hyphens, otherwise the recovery fails; and the Apple pass type identifier of the request must be the one configured for the tenant, otherwise the recovery is declined with a warning and the device gets "not found". The script runs inside the device's request, which waits for it for at most 10 seconds.

When the script returns a pass, The Wallet Crew creates it with the serial number and authentication token of the request, the pass type and the identifiers returned, then authenticates the device's request against it and registers the device, as for any known pass. The creation goes through the usual creation steps, including the `OnPassCreating` and `OnPassCreated` hooks of the [pass updater](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-updater.md). When two devices ask for the same unknown pass at the same time, only one pass is created and both are served from it.

## Handlers

| Method               | Parameters | Returns                                            | Required |
| -------------------- | ---------- | -------------------------------------------------- | -------- |
| `ResolveMissingPass` | `request`  | a promise of `{ passType, identifiers }` or `null` | Required |

`request` uses camelCase keys:

| Key                       | Meaning                                                                           |
| ------------------------- | --------------------------------------------------------------------------------- |
| `serialNumber`            | The serial number the device knows.                                               |
| `applePassTypeIdentifier` | The Apple pass type identifier of the pass, already checked against the tenant's. |
| `authenticationToken`     | The authentication token the device presents for that pass.                       |

{% hint style="warning" %}
The resolver decides who gets a pass. It must verify the pair `serialNumber` and `authenticationToken` against a trusted source before returning anything: a serial number alone can be guessed or copied. The token is a credential: it must never be logged.
{% endhint %}

## Return value

The result uses camelCase keys:

| Key           | Meaning                                                                                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `passType`    | Required. A pass type of the tenant, with its file `server/passes/<passType>.yml`.                                                                                                                                    |
| `identifiers` | Required. The identifiers the new pass carries, keyed without the `id.` prefix (`{ 'crm.customerId': '1042' }`). At least one; no empty key or value; the key `neo.id` is not allowed (reserved, see the note below). |

| Returned                    | Effect                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `{ passType, identifiers }` | The pass is created and the device registered.                                          |
| `null`                      | Recovery declined: the source does not know this pass, and the device gets "not found". |

The prefix `neostore` is the platform's former name and is kept in technical identifiers such as `neo.id`. At pass creation, the identifier `neo.id` sets the pass id. The resolver cannot return it, because the recovered pass takes as id the serial number the device knows.

A `null` answer is final for that request, so it is reserved for passes the trusted source does not know. When the source cannot be reached, the script throws instead.

## Errors and edge cases

* **The script throws or its promise rejects, or takes longer than 10 seconds**: the recovery fails and the device's request fails. Only the type of the error is recorded, never its message, because a message could contain credentials.
* **The result is invalid** (blank `passType`, a pass type the tenant does not have, no identifier, an empty key or value, or the key `neo.id`): the recovery fails.
* **More than one script registers the key**: every recovery fails.
* **No script registers the key**: unknown serial numbers are answered "not found", as without a resolver.
* **ResolveMissingPass is missing** from the registered object: the recovery fails.

## Example

The previous platform's export has been loaded into a migration service of the brand, which answers with the customer and the pass type for a serial number and token pair, `404` for an unknown pair. A transient failure throws, so the device's request fails instead of receiving a final "not found".

```js
import { getSecret } from 'twc/secrets';

const LOOKUP_URL = 'https://migration.example.com/api/apple-passes/lookup';
const PASS_TYPES = { loyalty: 'loyalty-card', vip: 'loyalty-card-vip' };

async function resolveMissingPass(request) {
  const apiKey = await getSecret('MIGRATION-API-KEY');
  const response = await fetch(LOOKUP_URL, {
    Method: 'POST',
    Headers: { 'X-Api-Key': apiKey },
    Body: { serialNumber: request.serialNumber, authenticationToken: request.authenticationToken },
    ThrowOnError: false
  });

  if (response.StatusCode === 404) {
    return null;
  }
  if (response.StatusCode !== 200 || !response.ResponseText) {
    throw new Error(`Migration lookup failed with status ${response.StatusCode}`);
  }

  const pass = JSON.parse(response.ResponseText);
  const passType = PASS_TYPES[pass.program];
  if (!passType || !pass.customerId) {
    return null;
  }

  return {
    passType,
    identifiers: { 'crm.customerId': String(pass.customerId) }
  };
}

export default function (context) {
  context.register('runtime.wallet.applePassResolver', {
    ResolveMissingPass: resolveMissingPass
  });
}
```

## Checking the result

A recovered pass appears in the pass list of the admin console with the serial number the device knew, and `GET /api/{tenantId}/passes/{serialNumber}` returns it. Every successful recovery is recorded at information level with the pass id, pass type and Apple pass type identifier, and every declined one with a warning, which The Wallet Crew support can look up.

## Common pitfalls

* The returned pass type is the display name rather than the file name of the pass type.
* The script trusts the serial number and ignores the token.

## FAQ

<details>

<summary><strong>Can the resolver stay registered after the migration?</strong></summary>

It does no harm while the trusted source stays available, since it only runs for unknown serial numbers. When the source is decommissioned, the registration is removed so that unknown passes are answered "not found" directly.

</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/apple-pass-resolver.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
