Choose a version:

PinPad API

The PinPad API provides secure PIN entry functionality for POS UI extensions, allowing you to display modal PIN pad interfaces for secure PIN collection, validation, and processing with customizable options and callback handling. The API enables secure authentication workflows within your extensions.

Anchor to Use casesUse cases

Staff authentication: Implement secure authentication requiring PIN verification from staff.
Access control: Create access control for sensitive operations like refunds or voids.
Authorization: Build security features requiring PIN-based authorization for critical actions.
Secure entry: Create secure data entry workflows requiring PIN confirmation.

Support

Targets (28)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides secure PIN entry functionality. Access the following properties on shopify to display PIN pad interfaces for authentication and secure input.

Anchor to showPinPad showPinPad (onSubmit: (pin: number[]) => | Promise<>, options?: ) => void required: Shows a PIN pad to the user in a modal dialog. The onSubmit function is called when the PIN is submitted and should validate the PIN, returning 'accept' or 'reject'.

• When accepted: The modal dismisses and triggers the onDismissed callback—perform any post-validation navigation in this callback rather than in onSubmit.

• When rejected: Displays the optional errorMessage and keeps the modal open.

Use for implementing secure authentication workflows, access control, or PIN-based verification systems.

PinValidationResult

Represents the validation outcome for an entered PIN. Indicates whether the PIN should be accepted or rejected, with optional error messaging for rejected PINs.

{result: 'accept'} | {result: 'reject'; errorMessage?: string}

PinPadOptions

Specifies configuration options for displaying the PIN pad interface. Includes callback functions for PIN entry events, dismissal handling, and customizable labels and messaging.

autoSubmit
Whether the pin should be automatically submitted when the user has entered the maximum PIN length. Use for PIN entry experiences where users don't need to manually submit after entering the required digits.
```
boolean
```
label
The content for the prompt on the pin pad. Use to provide clear instructions or context about what the PIN is being used for.
```
string
```
masked
Whether the entered PIN should be masked for security. When `true`, PIN digits are hidden from view. Use for secure PIN entry where visual privacy is important.
```
boolean
```
maxPinLength
The maximum length of the PIN (4-10 digits). Use to limit PIN length based on your security policies or authentication system constraints.
```
PinLength
```
minPinLength
The minimum length of the PIN (4-10 digits). Use to enforce PIN length requirements based on your security policies or authentication system requirements.
```
PinLength
```
onDismissed
The function to be called when the pin pad modal is dismissed. Receives a `PinPadResult` indicating whether PIN entry was completed and the entered PIN if available. Use for handling modal dismissal and processing final PIN results.
```
(result: PinPadResult) => void
```
onPinEntry
The function to be called when a pin is entered. Use for real-time PIN validation, progress feedback, or implementing custom PIN entry handling logic.
```
(pin: number[]) => void
```
pinPadAction
The call to action between the entry view and the keypad, consisting of a label and function that returns the pin. Use for custom PIN entry workflows or implementing specific authentication patterns.
```
PinPadActionType
```
title
The title shown in the modal header. Use to provide context about the PIN entry purpose or identify the specific authentication requirement.
```
string
```

PinLength

The valid PIN length values (4-10 digits). Commonly used to configure minimum and maximum PIN length requirements.

4 | 5 | 6 | 7 | 8 | 9 | 10

PinPadResult

Represents the result of a PIN pad interaction, indicating whether PIN entry was completed and providing the entered PIN if available.

completed
Whether the PIN entry was completed successfully. When `true`, the user entered a PIN and submitted it (or it was auto-submitted). When `false`, the user canceled the PIN pad modal without completing entry, typically by clicking a cancel button or dismissing the modal.
```
boolean
```
pin
The entered PIN as an array of individual digits (for example, `[1, 2, 3, 4]` for PIN "1234"). Each element is a number from 0-9. This array's length will be between `minPinLength` and `maxPinLength` inclusive. Only present when `completed` is `true`—when `completed` is `false`, this field is `undefined` since no PIN was entered.
```
number[]
```

PinPadActionType

Defines a custom action button for the PIN pad interface with a label and click handler.

label
The content for the prompt on the pin pad. Use to provide clear instructions or context about what the PIN is being used for.
```
string
```
onClick
Called when the action button is clicked. Can return the PIN digits directly as an array of numbers, or return a Promise that resolves to the PIN array. Use for implementing custom PIN retrieval logic or validation workflows.
```
() => number[] | Promise<number[]>
```

Examples

jsx

import { PinPadOptions } from '@shopify/ui-extensions/point-of-sale';

import { render } from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const VALID_PIN = '123456';

const options: PinPadOptions = {

label: 'Enter PIN to proceed',

title: 'PIN Pad Demo',

masked: true,

minPinLength: 6,

maxPinLength: 8,

};

const onShowTapped = () => {

shopify.pinPad.showPinPad((pin) => {

if (pin.join('') === VALID_PIN) {

console.log('PIN is valid');

return { result: 'accept' };

} else {

console.log('PIN is invalid');

return {

result: 'reject',

errorMessage: 'Invalid PIN, please try again',

};

}

}, options);

};

return (

<s-page heading="PIN Pad API">

<s-button onClick={onShowTapped}>Show Pin Pad</s-button>

</s-page>

);

}

Examples

Description

Present a secure PIN pad interface to collect and validate user PINs for authentication or verification. This example shows how to use `shopify.pinPad.show()` to display a PIN entry modal with customizable options. By handling the entered PIN securely and processing the result, you can implement secure authentication workflows.

jsx

import { PinPadOptions } from '@shopify/ui-extensions/point-of-sale';
import { render } from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const VALID_PIN = '123456';

  const options: PinPadOptions = {
    label: 'Enter PIN to proceed',
    title: 'PIN Pad Demo',
    masked: true,
    minPinLength: 6,
    maxPinLength: 8,
  };

  const onShowTapped = () => {
    shopify.pinPad.showPinPad((pin) => {
      if (pin.join('') === VALID_PIN) {
        console.log('PIN is valid');
        return { result: 'accept' };
      } else {
        console.log('PIN is invalid');
        return {
          result: 'reject',
          errorMessage: 'Invalid PIN, please try again',
        };
      }
    }, options);
  };

  return (
    <s-page heading="PIN Pad API">
      <s-button onClick={onShowTapped}>Show Pin Pad</s-button>
    </s-page>
  );
}

Anchor to Best practicesBest practices

Implement secure PIN validation: Validate PINs securely on your backend service rather than in client-side code, using the onSubmit callback to communicate with your secure validation endpoint.
Provide clear user feedback: Use appropriate labels, titles, and error messages to guide users through the PIN entry process.
Handle PIN entry appropriately: Implement proper error handling for PIN validation failures, provide retry mechanisms, and ensure sensitive PIN data is handled securely throughout the process.
Configure appropriate PIN constraints: Set reasonable PIN length requirements and masking options based on your security requirements and user experience considerations.

Anchor to LimitationsLimitations

PIN validation must be handled through the onSubmit callback and should be performed securely on your backend service rather than in client-side extension code.

Was this page helpful?