# Demo App Walkthrough

The Finix Tap to Pay on iPhone demo app is a small SwiftUI reference integration that allows you to run test transactions. Running it first gives you a working example to reference before building the flow into your own app.

Tap to Pay entitlement required
Do not continue until Apple has granted your [Tap to Pay on iPhone entitlement](/ios/tap-to-pay/getting-started#request-the-tap-to-pay-entitlement). The demo app will not run without it.

**Before you start**, complete the [Getting Started](/ios/tap-to-pay/getting-started) guide. You'll need:

- Apple's Tap to Pay on iPhone entitlement granted to your developer account.
- A sandbox Apple Account to sign in on the test iPhone.
- Your Finix merchant credentials and IDs from the Finix Dashboard.


Each Finix Device is keyed to the merchant and the iPhone's serial number. The Device you create here uses the demo app's `app_bundle_id`. When you [integrate the SDK into your application](/ios/tap-to-pay/integration), create a separate Device for your production app's Bundle Identifier.

## 1. Download and Open the Demo App

1. Go to the [demo app repository](https://github.com/finix-payments/finix-taptopay-ios-sdk-demo-app) on GitHub.
2. Click **Code** → **Download ZIP** (or clone the repo).


1. Open `FinixTapToPaySDKDemo.xcodeproj` in Xcode.


## 2. Add a Demo App Bundle ID

The demo app's Bundle Identifier is what you'll use to create a Finix Device. Change the default identifier to one belonging to your team, then copy it.

1. In Xcode, select the **FinixTapToPaySDKDemo** project in the navigator.
2. Select the **FinixTapToPaySDKDemo** target and go to **Signing & Capabilities**.
3. Under **Signing**, change the default **Bundle Identifier** (e.g., `com.yourcompany.FinixTapToPayDemo`).
4. Copy the new **Bundle Identifier**; you'll need it in the next step.


1. Select your **Team**.


## 3. Sign In to Your iPhone with the Sandbox Account

Sign your test iPhone in to the [Sandbox Apple Account](/ios/tap-to-pay/getting-started#create-an-apple-sandbox-account):

1. Open the **Settings** app on the iPhone.
2. Tap your name at the top and sign out of the current Apple Account.
3. Sign in with the Sandbox Apple Account you created.


Use a dedicated test iPhone
Signing in replaces the device's iCloud identity (photos, messages, iCloud Drive). Use a dedicated test iPhone rather than a personal device.

## 4. Create a Finix Device

Create a Finix Device resource for the demo app bundle ID you just copied. Provide the `app_bundle_id` from the previous step.

Use the demo app Bundle Identifier
Each Device uses a single `app_bundle_id` and is keyed to the merchant and this iPhone. Use the [demo app's Bundle Identifier](#2-add-a-demo-app-bundle-id) here, not the Bundle Identifier of the production app you plan to [integrate with the Tap to Pay iOS SDK](/ios/tap-to-pay/integration) later.

```bash
curl -i -X POST \
  -u {your_api_key}:{your_api_secret} \
  https://finix.sandbox-payments-api.com/merchants/{merchant_id}/devices \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "app_bundle_id": "{your_demo_app_bundle_id}",
    "description": "iOS Tap to Pay demo device",
    "model": "IOS_TAP_TO_PAY",
    "name": "iPhone Tap to Pay Demo - {merchant name}",
    "serial_number": "{reader_identifier}"
  }'
```

Substitute your [demo app's Bundle Identifier](#2-add-a-demo-app-bundle-id) for `{your_demo_app_bundle_id}`. In your real integration, `serial_number` is Apple's per-device reader identifier obtained at runtime via `PaymentCardReader().readerIdentifier`; see the [Integration Guide](/ios/tap-to-pay/integration#5-create-a-finix-device) and [Device](/ios/tap-to-pay/device-setup) in the SDK Reference for the production pattern.

Copy the `id` from the response; you need it to [activate the Device](#5-activate-the-device) and to configure the demo app.

Create a Device - Model IOS_TAP_TO_PAY
```json Create a Device - Model IOS_TAP_TO_PAY
{
  "id": "DVhNuqCgLmtHs6ZS9RSucm9x",
  "created_at": "2026-09-25T20:05:14.758628Z",
  "updated_at": "2026-09-25T20:05:14.758628Z",
  "configuration_details": { // [!code highlight]
    "allow_debit": true,
    "allow_standalone_authorizations": false,
    "allow_standalone_refunds": false,
    "allow_standalone_sales": false,
    "automatic_receipt_delivery_methods": null,
    "available_receipt_methods": null,
    "bypass_device_on_capture": true,
    "check_for_duplicate_transactions": true,
    "display_tip_on_receipt": false,
    "idle_image_file_id": null,
    "idle_message": null,
    "prompt_amount_confirmation": true,
    "prompt_for_signature": "NEVER",
    "prompt_manual_entry": false,
    "prompt_receipt_confirmation": true,
    "prompt_tip_on_screen": false,
    "signature_threshold_amount": 10000,
    "surcharge_basis_points": null,
    "tipping_details": {
      "fixed_options": [
        100,
        150,
        200
      ],
      "percent_options": [
        18,
        20,
        22
      ],
      "percent_tipping_threshold": 0
    }
  },
  "description": "iOS Tap to Pay device",
  "enabled": true,
  "idle_message": null,
  "integration_mode": "PAYMENT_APP",
  "merchant": "MUiV7ntxfY4eyJxp6E7cZvym",
  "model": "IOS_TAP_TO_PAY", // [!code highlight]
  "name": "iPhone Tap to Pay - Michael Johnson",
  "serial_number": "cdb7ac638cb455f6d85e791115c0a4fd3cf6cbcdb874cbf30c871bc312zy3abc",
  "tags": {},
  "_links": {
    "self": {
      "href": "https://finix.sandbox-payments-api.com/devices/DVhNuqCgLmtHs6ZS9RSucm9x"
    },
    "merchant": {
      "href": "https://finix.sandbox-payments-api.com/merchants/MUiV7ntxfY4eyJxp6E7cZvym"
    },
    "transfers": {
      "href": "https://finix.sandbox-payments-api.com/transfers"
    },
    "authorizations": {
      "href": "https://finix.sandbox-payments-api.com/authorizations"
    }
  }
}
```

The example response above shows `"enabled": true` because it is a shared fixture. A newly-created Device actually returns with `"enabled": false` and must be activated in the next step.

## 5. Activate the Device

The Device is disabled by default. Activate it before running the demo app.

```bash
curl -i -X PUT \
  -u {your_api_key}:{your_api_secret} \
  https://finix.sandbox-payments-api.com/devices/{device_id} \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{ "action": "ACTIVATE" }'
```

A successful response returns the Device with `"enabled": true`.

## 6. Build and Run the Demo App

1. In Xcode, select your connected iPhone as the run destination.
2. Click **Build and Run** (the play button).


Build warnings
The demo app may show build warnings. These are expected and do not prevent the app from running.

## 7. Configure the Demo App

When the app opens:

1. Tap the configuration button (the three-dots icon in the top-right corner).


1. Tap the **Sandbox** tab and enter the values you gathered previously:


| Value | Format | Where to find it |
|  --- | --- | --- |
| API username | `USxxxxxxxxxxxxx` | [From the Finix Dashboard](/ios/tap-to-pay/getting-started#creating-api-keys). |
| API password | Issued with the username. | Shown once in the Dashboard when the key is created. Treat as a secret. |
| Merchant ID | `MUxxxxxxxxxxxxx` | [From the Finix Dashboard](/ios/tap-to-pay/getting-started#locating-the-merchant-id). |
| Merchant display name | Shown to the Buyer on Apple's tap screen. | From the Merchant details page. |
| Device ID | `DVxxxxxxxxxxxxx` | Created in [Set up a Device](/ios/tap-to-pay/device-setup). |


Production tab
The Configuration screen also has a **Production** tab. You don't need it for the happy path. Once your own app is working in Sandbox, you'll move to production testing in your app rather than the demo. The tab is provided for debugging; functionally it is identical to Sandbox and only points at the production backend for card processing.

## 8. Link the Merchant Account

Before taking a payment, the merchant's Apple Account must be linked. In the demo app, tap the 3 dots in the top right corner, and tap **Link Account**.

If the account is not yet linked, Apple presents its Terms and Conditions screen. After the merchant accepts, the account is linked.

## 9. Prepare the Reader

Tap **Prepare**. The SDK readies the iPhone to accept payments in the background. When preparation completes, you'll see a success confirmation.

## 10. Run a Test Transaction

You may process sales, authorizations and refunds using the demo application.

To process a test transaction:

1. Confirm the reader is prepared by reading the logs.
2. Tap **Sale**.
3. Enter an **Amount**.
4. Tap **Tap to Pay on iPhone**.


When prompted, tap the Finix sandbox test card (or an Apple Pay Sandbox test card) against the iPhone.

The demo app indicates if the transaction succeeded or failed.

## 11. Next Steps

With a working reference integration, continue to the [Integration guide](/ios/tap-to-pay/integration) to add the Tap to Pay iOS SDK to your own app.