# Compatible Apps Registry

Fluxis maintains a public JSON registry of wallet and payment applications that support the NASPIP protocol. Frontends use this file to render a **"Pay with…"** picker: logos, store links, and deep links that open the user's chosen app with a payment token already attached.

## Registry URL

The registry is served as static JSON from Fluxis CDN:

```
https://assets.fluxis.us/sdk-assets/compatible-apps.json
```

Fetch it at runtime (for example from a checkout page or mobile web view). No authentication is required. The file is updated as new applications integrate with Fluxis.

## What it is for

When a merchant presents a NASPIP token (QR code, hosted checkout, or in-app payment sheet), the payer needs to know **which apps can complete the payment**. The compatible apps registry answers that question in a single, cache-friendly request.

Typical frontend usage:

1. Load `compatible-apps.json`.
2. Render each entry as a button or list row (logo + display name).
3. When the user selects an app, replace the `[NASPIP_TOKEN]` placeholder in `deep_link` with the actual NASPIP token from your payment request.
4. Open the resulting URL (mobile deep link or universal link) so the wallet receives the token.

If an app has no deep link yet, you can still show its logo and link to `website_url`, `app_store_url`, or `google_play_url` so users can install the app and pay via QR instead.

## Schema

The file is a **JSON array**. Each element describes one compatible application:

| Field | Type | Description |
| ----- | ---- | ----------- |
| `name` | `string` | Stable machine identifier (lowercase slug). Use this as a React key or analytics dimension. |
| `display_name` | `string` | Human-readable name shown in the UI. |
| `image_url` | `string` | Absolute URL to the app logo (SVG or PNG). |
| `website_url` | `string` | Official website. |
| `app_store_url` | `string \| null` | Apple App Store link, if available. |
| `google_play_url` | `string \| null` | Google Play link, if available. |
| `deep_link` | `string \| null` | URL template to open the app with a NASPIP token. See [Deep link placeholder](#deep-link-placeholder). |

All URLs are absolute. Nullable fields use JSON `null` when not applicable.

### Example entry

```json
{
  "name": "belo",
  "display_name": "Belo App",
  "image_url": "https://assets.fluxis.us/apps/belo.svg",
  "website_url": "https://belo.app",
  "app_store_url": "https://apps.apple.com/bo/app/belo-tu-pasaporte-financiero/id1575614708",
  "google_play_url": "https://play.google.com/store/apps/details?id=com.belo.android",
  "deep_link": "https://api.belo.app/dynamic-link?route=qri-scanner&naspip_token=[NASPIP_TOKEN]"
}
```

### Current registry (illustrative)

The live file at [compatible-apps.json](https://assets.fluxis.us/sdk-assets/compatible-apps.json) is the source of truth. At the time of writing it includes integrations such as Belo, MetaMask, and Trust Wallet, each with app-specific deep link formats.

## Deep link placeholder

Every `deep_link` value includes the literal placeholder **`[NASPIP_TOKEN]`**. Before opening the link, replace it with the URL-encoded NASPIP token from your payment request (the `token` field returned by `POST /v1/pos/:posID/payment-request`).

```javascript
function buildDeepLink(template, naspipToken) {
  return template.replace(
    "[NASPIP_TOKEN]",
    encodeURIComponent(naspipToken),
  );
}

// Example
const deepLink = buildDeepLink(
  app.deep_link,
  paymentRequest.token,
);
window.location.href = deepLink;
```

::::tip
For background on presenting NASPIP tokens in checkout, see [Step 5.1 — Displaying the NASPIP token](/docs/developers/tutorials/api-integration-guide#51-displaying-the-naspip-token) in the API Integration Guide.
::::

## When `deep_link` is `null`

Not every integrated app exposes a deep link yet. In those cases:

- `deep_link` is `null`.
- The app is still listed so users know it supports Fluxis / NASPIP.
- Your UI should fall back to store links or instruct the user to scan the NASPIP QR code inside the app.

Only show a **"Pay with [app]"** action that opens a deep link when `deep_link` is non-null.

## Growing the registry

The registry is **curated by Fluxis**. As wallet and payment applications integrate our protocol and provide a deep link template, we add them to this file.

If you are building a wallet or payment app and want to be listed:

1. Implement NASPIP token handling ([Implementation Guide](/docs/key-concepts/naspip/implementation-guide)).
2. Provide a deep link URL template with the `[NASPIP_TOKEN]` placeholder (or document that deep links are not available yet).
3. Supply branding assets (`image_url`) and store links.
4. Contact [support@fluxis.us](mailto:support@fluxis.us) with your integration details.

We update `compatible-apps.json` on the CDN; frontends do not need to redeploy to pick up new apps if they fetch the file at runtime. Consider short HTTP caching (for example 5–15 minutes) so users see new wallets without stale data living forever.

## Frontend integration example

```javascript
const REGISTRY_URL =
  "https://assets.fluxis.us/sdk-assets/compatible-apps.json";

async function loadCompatibleApps() {
  const res = await fetch(REGISTRY_URL);
  if (!res.ok) throw new Error("Failed to load compatible apps");
  return res.json();
}

function renderPayWithApp(app, naspipToken) {
  if (!app.deep_link) {
    // No deep link — link to store or show QR-only flow
    return app.website_url;
  }
  return app.deep_link.replace(
    "[NASPIP_TOKEN]",
    encodeURIComponent(naspipToken),
  );
}
```

## Related documentation

- [NASPIP Token — Introduction](/docs/key-concepts/naspip/introduction)
- [API Integration Guide](/docs/developers/tutorials/api-integration-guide)
- [Payment Request](/docs/key-concepts/payment-request)