--- title: PinPad description: >- The `PinPad` component provides a secure numeric keypad interface for PIN entry and validation. Use it to collect PIN codes, passcodes, or other sensitive numeric input with proper masking and validation. The component provides a secure numeric input interface specifically designed for PIN entry, with visual feedback that masks entered digits for security. It includes built-in validation for PIN length requirements, supports error states for invalid PINs, and provides haptic feedback on touch-enabled devices to confirm key presses during secure authentication workflows. `PinPad` components meets security standards for PIN entry by preventing screenshot capture and display recording, protecting sensitive authentication data during payment authorization and staff access workflows. api_version: 2024-07 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/pinpad md: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-07/ui-components/forms/pinpad.md --- # Pin​Pad The `PinPad` component provides a secure numeric keypad interface for PIN entry and validation. Use it to collect PIN codes, passcodes, or other sensitive numeric input with proper masking and validation. The component provides a secure numeric input interface specifically designed for PIN entry, with visual feedback that masks entered digits for security. It includes built-in validation for PIN length requirements, supports error states for invalid PINs, and provides haptic feedback on touch-enabled devices to confirm key presses during secure authentication workflows. `PinPad` components meets security standards for PIN entry by preventing screenshot capture and display recording, protecting sensitive authentication data during payment authorization and staff access workflows. Support Targets (6) ### Supported targets * [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/customer-details#customer-details-action-modal-) * [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/draft-order-details#draft-order-details-action-modal-) * [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/home-screen#home-screen-action-modal-) * [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/order-details#order-details-action-modal-) * [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/product-details#product-details-action-modal-) * [pos.​purchase.​post.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/post-purchase#post-purchase-action-modal-) #### Use cases * **Staff authentication:** Implement secure PIN verification for staff authentication or manager overrides. * **Sensitive operations:** Enable passcode entry for refunds, voids, or cash drawer access. * **Loyalty verification:** Provide secure numeric input for loyalty card PINs or gift card verification. * **Time tracking:** Create employee clock-in/clock-out interfaces requiring PIN identification. ## Examples ### Validate a PIN securely Collect and validate PINs securely using a numeric keypad interface. This example demonstrates a PinPad with an `onPinSubmit` callback that validates entered PINs asynchronously. The validation function receives an array of numbers representing the entered digits and returns a Promise that resolves to `PinValidationResult` (either `"accept"` or `"reject"`). In this example, the validation simulates a 1-second async check against a test PIN sequence \[1, 2, 3, 4, 5, 6]. The component masks digits for security, provides haptic feedback, and supports error states for invalid PINs—ideal for payment authorization or staff access workflows. ## Validate a PIN securely ![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2024-07/pin-pad-default.png) ### Examples * #### Validate a PIN securely ##### Description Collect and validate PINs securely using a numeric keypad interface. This example demonstrates a PinPad with an \`onPinSubmit\` callback that validates entered PINs asynchronously. The validation function receives an array of numbers representing the entered digits and returns a Promise that resolves to \`PinValidationResult\` (either \`"accept"\` or \`"reject"\`). In this example, the validation simulates a 1-second async check against a test PIN sequence \[1, 2, 3, 4, 5, 6]. The component masks digits for security, provides haptic feedback, and supports error states for invalid PINs—ideal for payment authorization or staff access workflows. ##### Default ```ts const onPinSubmit = (pin: number[]): Promise => { return new Promise((resolve) => { setTimeout(() => { const isPinValid = pin.length === 6 && pin.every((digit, index) => digit === index + 1); const result: PinValidationResult = isPinValid ? 'accept' : 'reject'; resolve(result); }, 1000); }); }; ``` ## Properties Configure the following properties on the `PinPad` component. * onSubmit (pin: number\[]) => Promise\ required A callback function executed when the PIN is submitted, receiving the PIN as an array of numbers. Must return a Promise that resolves to either `'accept'` or `'reject'` to indicate validation success or failure. * label string The content for the prompt displayed on the pin pad that instructs users what to enter. * masked boolean Whether the entered PIN should be masked with dots or asterisks to protect privacy and security. * maxPinLength PinLength The maximum length of the PIN that users can enter, constraining the number of digits. * minPinLength PinLength The minimum length of the PIN that users must enter before submission is allowed. * onPinEntry (pin: number\[]) => void A callback function executed when a PIN is entered, receiving the PIN as an array of numbers. Use this for real-time feedback or validation during PIN entry. * pinPadAction PinPadActionType A call-to-action configuration displayed between the entry view and the keypad, consisting of a label and function that returns the current PIN. ### PinLength Defines the allowed PIN length values that constrain how many digits users can enter. Available lengths: - \`4\`: A four-digit PIN length, commonly used for basic security codes and quick authentication. - \`5\`: A five-digit PIN length for moderate security requirements. - \`6\`: A six-digit PIN length, commonly used for enhanced security codes and verification. - \`7\`: A seven-digit PIN length for higher security requirements. - \`8\`: An eight-digit PIN length for strong security and complex authentication scenarios. - \`9\`: A nine-digit PIN length for very high security requirements. - \`10\`: A ten-digit PIN length, the maximum supported for highly secure authentication workflows. ```ts 4 | 5 | 6 | 7 | 8 | 9 | 10 ``` ### PinValidationResult Defines the validation result values that the \`onSubmit\` callback must return to indicate PIN verification status. Available values: - \`accept\`: A validation result indicating the PIN is correct and authentication was successful. - \`reject\`: A validation result indicating the PIN is incorrect and authentication failed. ```ts 'accept' | 'reject' ``` ### PinPadActionType Defines the configuration object for action buttons displayed between the PIN entry view and keypad. * label The label text displayed on the action button. ```ts string ``` * onPress A callback function executed when the action button is pressed, returning the current PIN as an array of numbers. ```ts () => Promise ``` ```ts export interface PinPadActionType { /** * The label text displayed on the action button. */ label: string; /** * A callback function executed when the action button is pressed, returning the current PIN as an array of numbers. */ onPress: () => Promise; } ``` ## Best practices * **Mask sensitive entry:** Set `masked` to true for security-related PIN entry to prevent shoulder-surfing. * **Set appropriate constraints:** Define `minPinLength` and `maxPinLength` based on security needs (4-6 for basic, 6-10 for higher security). * **Validate securely on backend:** Use `onSubmit` for server-side verification. Return `accept` or `reject`. Implement rate limiting. * **Write clear labels:** Use direct prompts like "Enter Manager PIN" rather than verbose text. * **Use PIN terminology:** Always use "PIN" in all capitals. ## Limitations * `PinPad` is designed for numeric PIN entry only—alphanumeric passcodes or complex passwords require different input components. * PIN length is constrained to 4-10 digits—requirements outside this range need alternative authentication methods. * The component provides the keypad interface and basic validation—additional security measures like rate limiting, attempt tracking, or lockout mechanisms must be implemented in your `onSubmit` callback.