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.

tapZone

required

TapZone

Defines the tap zone configuration (Large or Small)

Parameters

Copy

Copied

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:

Copy

Copied

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

Parameters

position	NfcPosition Default: "CENTER" NFC indicator position on screen Enum: "TOP_START" "TOP_CENTER" "TOP_END" "CENTER_START" "CENTER" "CENTER_END" "BOTTOM_START" "BOTTOM_CENTER" "BOTTOM_END"
orientation	DeviceOrientation Default: "PORTRAIT" Physical device orientation Enum: "PORTRAIT" "REVERSE_PORTRAIT" "LANDSCAPE" "REVERSE_LANDSCAPE"

External TapZone

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

Copy

Copied

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

Parameters

direction	NfcDirection Default: "NONE" NFC direction - currently only `NONE` is supported Value: "NONE"
orientation	DeviceOrientation Default: "PORTRAIT" Physical device orientation Enum: "PORTRAIT" "REVERSE_PORTRAIT" "LANDSCAPE" "REVERSE_LANDSCAPE"

Small TapZone

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

On-Device TapZone

Display the indicator using simplified positioning:

Copy

Copied

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

Parameters

position

NfcPosition

Default: "CENTER"

NFC indicator position on screen

Enum: "TOP" "CENTER" "BOTTOM"

External TapZone

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

Copy

Copied

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

Parameters

direction

NfcDirection

Default: "NONE"

NFC direction - currently only NONE is supported

Value: "NONE"

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

string

Device orientation values

Enum: "PORTRAIT" "REVERSE_PORTRAIT" "LANDSCAPE" "REVERSE_LANDSCAPE"

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

Copy

Copied

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

Copy

Copied

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

// Apply the configuration
TapToPaySdk.setTapToPayUxOption(options)

External NFC Reader

Copy

Copied

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)