Guidance Required on DSpread POS SDK onRequestDisplay Handling

[prabhatsdp]

Hi DSpread Team,

We are currently building a payment application using the DSpread POS SDK, and we want to ensure that we handle the onRequestDisplay(Display displayMsg) callback correctly for the best user experience and EMV-compliant transaction flow.

Could you please provide official guidance or best practices for the following points?

1. Recommended UI Handling for Display Enums

We want to understand how DSpread recommends presenting different Display states in the app UI.

Specifically, should these states be handled as:

• Blocking dialogs or full-screen blocking UI
• User-intervention messages requiring action
• Non-blocking transient messages
• Simple text updates on the transaction progress screen

For example:

• Which states should completely block the UI?
  Example: REMOVE_CARD, MAG_TO_ICC_TRADE

• Which states require active user intervention?
  Example: PlEASE_TAP_CARD_AGAIN

• Which states are only transient/progress messages?
  Example: PROCESSING, PLEASE_WAIT

2. Device-Specific Behaviour

We are targeting both Smart POS devices and mPOS/headless devices.

Target devices:

• Smart POS / screen-based devices: D60, D70
• mPOS / headless or basic LED devices: D30, CR100, QPOS Mini

Could you please confirm whether all Display enums are triggered across all device types, or whether some are specific to certain hardware profiles?

We especially need clarity around PIN-related callbacks:

• INPUT_PIN_ING
• INPUT_ONLINE_PIN
• INPUT_OFFLINE_PIN
• INPUT_OFFLINE_PIN_ONLY
• INPUT_LAST_OFFLINE_PIN
• INPUT_NEW_PIN
• CONFIRM_NEW_PIN
• INPUT_NEW_PIN_CHECK_ERROR

For example, how should these be handled differently when:

• The POS device has its own screen and PIN pad, such as D60
• The device is headless/basic, such as CR100, where the mobile app may need to render the PIN UI

3. Display Enum Reference

For reference, this is the enum list we are mapping from the SDK:

public static enum Display {
    PLEASE_WAIT,
    REMOVE_CARD,
    PROCESSING,
    PIN_OK,
    TRANSACTION_TERMINATED,
    INPUT_PIN_ING,
    MAG_TO_ICC_TRADE,
    INPUT_OFFLINE_PIN_ONLY,
    INPUT_LAST_OFFLINE_PIN,
    MSR_DATA_READY,
    NOT_ALLOWED_LOW_TRADE,
    PlEASE_TAP_CARD_AGAIN, // SDK spelling
    NFC_CLOSRD,            // SDK spelling
    INPUT_NEW_PIN,
    INPUT_NEW_PIN_CHECK_ERROR,
    CONFIRM_NEW_PIN,
    INPUT_ONLINE_PIN,
    INPUT_OFFLINE_PIN;
}

Any official sample code, UI mapping matrix, device-specific behaviour notes, or architectural guidance would be very helpful.

Thank you.

[fangzhengwei]

Hi @prabhatsdp Please check the below response.

1. Recommended UI Handling for Display Enums

Which states should completely block the UI?

• REMOVE_CARD
• TRANSACTION_TERMINATED
• NOT_ALLOWED_LOW_TRADE
• NFC_CLOSRD

Which states require active user intervention?

• INPUT_PIN_ING
• INPUT_OFFLINE_PIN_ONLY
• INPUT_ONLINE_PIN
• INPUT_OFFLINE_PIN
• PlEASE_TAP_CARD_AGAIN
• INPUT_NEW_PIN
• CONFIRM_NEW_PIN
• INPUT_NEW_PIN_CHECK_ERROR
• INPUT_LAST_OFFLINE_PIN
• MAG_TO_ICC_TRADE

Which states are only transient/progress messages?

• PROCESSING
• PLEASE_WAIT
• PIN_OK

"MSR_DATA_READY" is not used for all devices.

2. Device-Specific Behaviour

Some display enums are specific to certain hardware profiles, please check the below details.

Reader (CR100, it don't have screen and physical keyboard)

• When input online pin, device callback onRequestSetPin() method and onRequestDisplay(Display.INPUT_ONLINE_PIN).
• When input offline pin, device callback onRequestSetPin() method and onRequestDisplay(Display.INPUT_OFFLINE_PIN).
• When input last offline pin, device callback onRequestSetPin() method and onRequestDisplay(Display.INPUT_LAST_OFFLINE_PIN").

MPOS (QPOS mini, QPOS cute, they have screen and physical keyboard)

• When input online pin, device will callback onRequestDisplay(Display.INPUT_PIN_ING).
• When input offline pin, device will callback onRequestDisplay(Display.INPUT_OFFLINE_PIN_ONLY).
• When input last offline pin, device will callback onRequestDisplay(Display.INPUT_LAST_OFFLINE_PIN).

Smart POS(D20/D30/D50/D80,they have screen and don't have physical keyboard)

• When input online pin, device callback onQposRequestPinResult() & onReturnGetPinInputResult() method and onRequestDisplay(Display.INPUT_ONLINE_PIN).
• When input offline pin, device callback onQposRequestPinResult() & onReturnGetPinInputResult() method and onRequestDisplay(Display.INPUT_OFFLINE_PIN).
• When input last offline pin, device callback onQposRequestPinResult() & onReturnGetPinInputResult() method and onRequestDisplay(Display.INPUT_LAST_OFFLINE_PIN").
• When input new pin, device callback onQposRequestPinResult() & onReturnGetPinInputResult() method and onRequestDisplay(Display.INPUT_NEW_PIN").
• When confirm new pin, device callback onQposRequestPinResult() & onReturnGetPinInputResult() method and onRequestDisplay(Display.CONFIRM_NEW_PIN").
• When the new PIN entered the second time did not match the one entered the first time, device callback onRequestDisplay(Display.INPUT_NEW_PIN_CHECK_ERROR").

Smart POS(D70,D80K,they have screen and have physical keyboard)

• When input online pin, device will callback onRequestDisplay(Display.INPUT_ONLINE_PIN).
• When input offline pin, device will callback onRequestDisplay(Display.INPUT_OFFLINE_PIN).
• When input last offline pin, device will callback onRequestDisplay(Display.INPUT_LAST_OFFLINE_PIN).
• When input new pin, device callback onRequestDisplay(Display.INPUT_NEW_PIN").
• When confirm new pin, device callback onRequestDisplay(Display.CONFIRM_NEW_PIN").
• When the new PIN entered the second time did not match the one entered the first time, device callback onRequestDisplay(Display.INPUT_NEW_PIN_CHECK_ERROR").