Configure Tap to Pay UX Options

When to Customise

Position the NFC tap indicator to match your device's antenna location. Customise the NFC tap indicator position when:

• Your device's NFC antenna is located somewhere other than the center of the screen (default for both phones and tablets)
• Using external NFC hardware (use external to hide the on-screen indicator)
• Supporting consistent positioning

You can call the setTapToPayUxOption(...) and set the NFC tap indicator for both small and larger devices.

TapZone Configuration

Override the default configuration to defines where the NFC tap indicator should be displayed. Choose Large for tablets or Small for phones.

Parameters

val options = TapToPayUxOptions {
    tapZone(tapZone)
}

// Or using the builder
val options = TapToPayUxOptions.builder()
    .tapZone(tapZone)
    .build()

Large TapZone

For tablets and larger devices with 9-position grid layout and orientation support.

On-Device TapZone

Display the indicator at a specific screen position using a 3x3 grid:

val largeTapZone = TapToPayUxOptions.TapZone.large {
    onDevice {
        position(TapToPayUxOptions.TapZone.Large.OnDevice.NfcPosition.CENTER)
        orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)
    }
}

Parameters

External TapZone

This will hide the on-screen NFC tap indicator for the large device with external NFC antenna:

val largeTapZone = TapToPayUxOptions.TapZone.large {
    external {
        direction(TapToPayUxOptions.TapZone.Large.External.NfcDirection.NONE)
        orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)
    }
}

Parameters

Small TapZone

For phones and smaller devices with simplified 3-position layout.

On-Device TapZone

Display the indicator using simplified positioning:

val smallTapZone = TapToPayUxOptions.TapZone.small {
    onDevice {
        position(TapToPayUxOptions.TapZone.Small.OnDevice.NfcPosition.CENTER)
    }
}

Parameters

External TapZone

Hide the on-screen indicator for small devices with external NFC antenna:

val smallTapZone = TapToPayUxOptions.TapZone.small {
    external {
        direction(TapToPayUxOptions.TapZone.Small.External.NfcDirection.NONE)
    }
}

Parameters

Device Orientation

Available on large TapZone only.

The DeviceOrientation parameter tells the SDK the device's current physical orientation when configuring the position of NFC tap indicator. The SDK uses this to calculate where to position the tap indicator on screen so it stays in the correct physical location as the device rotates.

Rotation Support by Device Type

• Small devices (phones): Screen rotation is not supported. The screen remains in a fixed portrait orientation. You can configure the indicator position, but it will not adjust based on device orientation.
• Large devices (tablets): Screen rotation is supported. The tap indicator maintains its physical position relative to the device hardware when rotated.

Parameters

Example: If a device is set up with PORTRAIT for an NFC read in the top left of the device, then if rotated left 90°s into a LANDSCAPE orientation, the NFC tap indicator would be shown in the top-left of the screen, keeping the NFC tap indicator in the same physical position.

Complete Example

Large Device: Top-Center Position

val options = TapToPayUxOptions {
    tapZone(
        TapToPayUxOptions.TapZone.large {
            onDevice {
                position(TapToPayUxOptions.TapZone.Large.OnDevice.NfcPosition.TOP_CENTER)
                orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)
            }
        }
    )
}

// Apply the configuration
TapToPaySdk.setTapToPayUxOption(options)

Small Device: Top Position

val options = TapToPayUxOptions {
    tapZone(
        TapToPayUxOptions.TapZone.small {
            onDevice {
                position(TapToPayUxOptions.TapZone.Small.OnDevice.NfcPosition.TOP)
            }
        }
    )
}

// Apply the configuration
TapToPaySdk.setTapToPayUxOption(options)

External NFC Reader

val options = TapToPayUxOptions {
    tapZone(
        TapToPayUxOptions.TapZone.large {
            external {
                direction(TapToPayUxOptions.TapZone.Large.External.NfcDirection.NONE)
                orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)
            }
        }
    )
}

// Apply the configuration
TapToPaySdk.setTapToPayUxOption(options)