> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile App

> Add commerce to iOS / Android / React Native with Shoppex as a backend-for-frontend — your native UX, web-based payment finalization.

Sell digital goods, subscriptions, or licenses from a native app. The app owns UX. A small backend-for-frontend (BFF) you own holds the Shoppex API key and talks to `/dev/v1/*`. Payment finalization happens in the system browser and returns via deep link.

<Warning>
  If you are selling in-app digital content that is *consumed inside* the app, Apple App Store rules may require In-App Purchase. This pattern fits physical-feeling deliverables (license keys, external downloads, Discord roles, gaming keys) and subscriptions that unlock an external service. Check the current review guidelines before shipping.
</Warning>

## Why this works well

<CardGroup cols={2}>
  <Card title="No API key on device" icon="shield">
    The `shx_*` key stays on your BFF. The app only ever sees short-lived payment-session URLs.
  </Card>

  <Card title="Familiar auth shape" icon="user">
    Your app keeps its own login (OAuth, magic-link, social). Shoppex is only commerce.
  </Card>
</CardGroup>

## Flow

1. The app asks your BFF to buy a product.
2. Your BFF creates the payment in Shoppex.
3. The app opens the hosted checkout URL in the system browser.
4. Shoppex redirects back to your universal link or return page.
5. Your BFF receives the signed webhook and updates the buyer state.
6. The app shows the final state after polling or receiving a push notification.

## Shape

| Piece                                       | Responsibility                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------- |
| Native app                                  | UI, auth, deep-link handler, optimistic "Processing..." state             |
| Your BFF                                    | Exchange user session for Dev API calls, receive webhooks, push to device |
| Shoppex                                     | Catalog, payment session, PSP orchestration, webhook emission             |
| System browser / ASWebAuthenticationSession | The payment UI itself (required by PSP compliance)                        |

## Key choices

### Return URL should be a universal link, not a custom scheme

Universal links (iOS) / app links (Android) hand control back to your app without the "Open in app?" prompt and survive cold starts better than `myapp://`:

```text theme={"system"}
return_url: https://yourapp.com/return
cancel_url: https://yourapp.com/cancel
```

Your universal link route detects whether the app is installed and either deep-links or falls back to a web "open the app" screen.

### Use ASWebAuthenticationSession / Chrome Custom Tabs

Do not embed checkout in a `WKWebView` — PSPs may block it, 3DS flows may break, and Apple rejects apps that proxy payment forms. Use the system-provided authenticated browser surface.

### Optimistic UI

After the deep-link comes back, the app should show "Finalizing…" and poll `GET /dev/v1/payments/{uniqid}` until `status === 'COMPLETED'`. The webhook then triggers a push notification for confirmation. Both paths converge on the same order state.

## Pitfalls

* **Deep-link replay attacks** — treat the deep-link return as a *hint*, not proof of payment. Always confirm state via Dev API call or webhook before granting access.
* **App Store review** — Apple may reject apps that sell digital goods consumed in-app without IAP. External services, off-device benefits, or fulfillment outside the app are typically the safer fit, but you should still validate the exact flow before launch.
* **Push notifications lag** — webhooks arrive at your BFF in milliseconds, but APNs / FCM delivery can lag. The app's polling covers the gap.

## Related

<CardGroup cols={2}>
  <Card title="Architecture Reference" icon="sitemap" href="/headless/architecture">
    Setup C (Mobile + BFF) — full diagram and responsibility split.
  </Card>

  <Card title="Webhook Security" icon="shield" href="/api-reference/webhooks/overview">
    Timestamped signatures, retries, constant-time verification.
  </Card>
</CardGroup>