{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["json-schema"]},"type":"markdown"},"seo":{"title":"Configure Tap to Pay UX Options","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"configure-tap-to-pay-ux-options","__idx":0},"children":["Configure Tap to Pay UX Options"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-customise","__idx":1},"children":["When to Customise"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Position the NFC tap indicator to match your device's antenna location. Customise the NFC tap indicator position when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your device's NFC antenna is located somewhere other than the center of the screen (default for both phones and tablets)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using external NFC hardware (use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external"]}," to hide the on-screen indicator)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supporting consistent positioning"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setTapToPayUxOption(...)"]}," and set the NFC tap indicator for both small and larger devices."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tapzone-configuration","__idx":2},"children":["TapZone Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Override the default configuration to defines where the NFC tap indicator should be displayed. Choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Large"]}," for tablets or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Small"]}," for phones."]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","properties":{"tapZone":{"type":"TapZone","description":"Defines the tap zone configuration (Large or Small)"}},"required":["tapZone"]},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","properties":{"tapZone":{"type":"TapZone","description":"Defines the tap zone configuration (Large or Small)"}},"required":["tapZone"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parameters","__idx":3},"children":["Parameters"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val options = TapToPayUxOptions {\n    tapZone(tapZone)\n}\n\n// Or using the builder\nval options = TapToPayUxOptions.builder()\n    .tapZone(tapZone)\n    .build()\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"large-tapzone","__idx":4},"children":["Large TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For tablets and larger devices with 9-position grid layout and orientation support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"on-device-tapzone","__idx":5},"children":["On-Device TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the indicator at a specific screen position using a 3x3 grid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val largeTapZone = TapToPayUxOptions.TapZone.large {\n    onDevice {\n        position(TapToPayUxOptions.TapZone.Large.OnDevice.NfcPosition.CENTER)\n        orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"parameters-1","__idx":6},"children":["Parameters"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","properties":{"position":{"type":"NfcPosition","enum":["TOP_START","TOP_CENTER","TOP_END","CENTER_START","CENTER","CENTER_END","BOTTOM_START","BOTTOM_CENTER","BOTTOM_END"],"description":"NFC indicator position on screen","default":"CENTER"},"orientation":{"type":"DeviceOrientation","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Physical device orientation","default":"PORTRAIT"}}},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","properties":{"position":{"type":"NfcPosition","enum":["TOP_START","TOP_CENTER","TOP_END","CENTER_START","CENTER","CENTER_END","BOTTOM_START","BOTTOM_CENTER","BOTTOM_END"],"description":"NFC indicator position on screen","default":"CENTER"},"orientation":{"type":"DeviceOrientation","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Physical device orientation","default":"PORTRAIT"}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"external-tapzone","__idx":7},"children":["External TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This will hide the on-screen NFC tap indicator for the large device with external NFC antenna:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val largeTapZone = TapToPayUxOptions.TapZone.large {\n    external {\n        direction(TapToPayUxOptions.TapZone.Large.External.NfcDirection.NONE)\n        orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"parameters-2","__idx":8},"children":["Parameters"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","properties":{"direction":{"type":"NfcDirection","enum":["NONE"],"description":"NFC direction - currently only `NONE` is supported","default":"NONE"},"orientation":{"type":"DeviceOrientation","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Physical device orientation","default":"PORTRAIT"}}},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","properties":{"direction":{"type":"NfcDirection","enum":["NONE"],"description":"NFC direction - currently only `NONE` is supported","default":"NONE"},"orientation":{"type":"DeviceOrientation","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Physical device orientation","default":"PORTRAIT"}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"small-tapzone","__idx":9},"children":["Small TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For phones and smaller devices with simplified 3-position layout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"on-device-tapzone-1","__idx":10},"children":["On-Device TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the indicator using simplified positioning:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val smallTapZone = TapToPayUxOptions.TapZone.small {\n    onDevice {\n        position(TapToPayUxOptions.TapZone.Small.OnDevice.NfcPosition.CENTER)\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"parameters-3","__idx":11},"children":["Parameters"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","properties":{"position":{"type":"NfcPosition","enum":["TOP","CENTER","BOTTOM"],"description":"NFC indicator position on screen","default":"CENTER"}}},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","properties":{"position":{"type":"NfcPosition","enum":["TOP","CENTER","BOTTOM"],"description":"NFC indicator position on screen","default":"CENTER"}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"external-tapzone-1","__idx":12},"children":["External TapZone"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hide the on-screen indicator for small devices with external NFC antenna:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val smallTapZone = TapToPayUxOptions.TapZone.small {\n    external {\n        direction(TapToPayUxOptions.TapZone.Small.External.NfcDirection.NONE)\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"parameters-4","__idx":13},"children":["Parameters"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","properties":{"direction":{"type":"NfcDirection","enum":["NONE"],"description":"NFC direction - currently only `NONE` is supported","default":"NONE"}}},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","properties":{"direction":{"type":"NfcDirection","enum":["NONE"],"description":"NFC direction - currently only `NONE` is supported","default":"NONE"}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"device-orientation","__idx":14},"children":["Device Orientation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Available on large TapZone only."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rotation-support-by-device-type","__idx":15},"children":["Rotation Support by Device Type"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Large devices (tablets)"]},": Screen rotation is supported. The tap indicator maintains its physical position relative to the device hardware when rotated."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parameters-5","__idx":16},"children":["Parameters"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"string","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Device orientation values","properties":{"PORTRAIT":{"description":"Standard upright position"},"REVERSE_PORTRAIT":{"description":"Upside down position"},"LANDSCAPE":{"description":"Rotated 90° left"},"REVERSE_LANDSCAPE":{"description":"Rotated 90° right"}}},"options":{"schemaExpansionLevel":1},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"string","enum":["PORTRAIT","REVERSE_PORTRAIT","LANDSCAPE","REVERSE_LANDSCAPE"],"description":"Device orientation values","properties":{"PORTRAIT":{"description":"Standard upright position"},"REVERSE_PORTRAIT":{"description":"Upside down position"},"LANDSCAPE":{"description":"Rotated 90° left"},"REVERSE_LANDSCAPE":{"description":"Rotated 90° right"}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]},": If a device is set up with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PORTRAIT"]}," for an NFC read in the top left of the device, then if rotated left 90°s into a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example","__idx":17},"children":["Complete Example"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"large-device-top-center-position","__idx":18},"children":["Large Device: Top-Center Position"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val options = TapToPayUxOptions {\n    tapZone(\n        TapToPayUxOptions.TapZone.large {\n            onDevice {\n                position(TapToPayUxOptions.TapZone.Large.OnDevice.NfcPosition.TOP_CENTER)\n                orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)\n            }\n        }\n    )\n}\n\n// Apply the configuration\nTapToPaySdk.setTapToPayUxOption(options)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"small-device-top-position","__idx":19},"children":["Small Device: Top Position"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val options = TapToPayUxOptions {\n    tapZone(\n        TapToPayUxOptions.TapZone.small {\n            onDevice {\n                position(TapToPayUxOptions.TapZone.Small.OnDevice.NfcPosition.TOP)\n            }\n        }\n    )\n}\n\n// Apply the configuration\nTapToPaySdk.setTapToPayUxOption(options)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"external-nfc-reader","__idx":20},"children":["External NFC Reader"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"val options = TapToPayUxOptions {\n    tapZone(\n        TapToPayUxOptions.TapZone.large {\n            external {\n                direction(TapToPayUxOptions.TapZone.Large.External.NfcDirection.NONE)\n                orientation(TapToPayUxOptions.TapZone.DeviceOrientation.PORTRAIT)\n            }\n        }\n    )\n}\n\n// Apply the configuration\nTapToPaySdk.setTapToPayUxOption(options)\n","lang":"kotlin"},"children":[]}]},"headings":[{"value":"Configure Tap to Pay UX Options","id":"configure-tap-to-pay-ux-options","depth":1},{"value":"When to Customise","id":"when-to-customise","depth":2},{"value":"TapZone Configuration","id":"tapzone-configuration","depth":2},{"value":"Parameters","id":"parameters","depth":3},{"value":"Large TapZone","id":"large-tapzone","depth":2},{"value":"On-Device TapZone","id":"on-device-tapzone","depth":3},{"value":"Parameters","id":"parameters-1","depth":4},{"value":"External TapZone","id":"external-tapzone","depth":3},{"value":"Parameters","id":"parameters-2","depth":4},{"value":"Small TapZone","id":"small-tapzone","depth":2},{"value":"On-Device TapZone","id":"on-device-tapzone-1","depth":3},{"value":"Parameters","id":"parameters-3","depth":4},{"value":"External TapZone","id":"external-tapzone-1","depth":3},{"value":"Parameters","id":"parameters-4","depth":4},{"value":"Device Orientation","id":"device-orientation","depth":2},{"value":"Rotation Support by Device Type","id":"rotation-support-by-device-type","depth":3},{"value":"Parameters","id":"parameters-5","depth":3},{"value":"Complete Example","id":"complete-example","depth":2},{"value":"Large Device: Top-Center Position","id":"large-device-top-center-position","depth":3},{"value":"Small Device: Top Position","id":"small-device-top-position","depth":3},{"value":"External NFC Reader","id":"external-nfc-reader","depth":3}],"frontmatter":{"title":"Set Tap to Pay UX Options","seo":{"title":"Configure Tap to Pay UX Options"}},"lastModified":"2026-09-02T01:02:13.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/tap-to-pay/android/sdk/set-tap-to-pay-ux-options","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}