Change a PIN

To limit the exposure of the PIN in a physical card, the issuer application delegates the task of changing the PIN to D1 SDK.

These are the PIN formats (from issuer backend) that are currently supported:

PIN ISO0
PIN 3DES Seccos

User Experience

Flow

The user authenticates on the banking app and request to change the PIN
An internal call is made to the SDK
Capture securely the PIN
D1 BackEnd API
D1 transciphers the PIN from device key to Issuer key
Set the PIN to Issuer backend

Sequence Diagram

Pre-requisites

Consumer, account and card already registered in D1
SDK is properly initialized
Issuer App called D1 SDK login API.

Required APIs

API

Inbound/Outbound

Description

Get authorization token

Issuer <- Thales D1

Get an OAuth 2.0 access token to call the Issuer backend.

Set PIN

Issuer <- Thales D1

Set the PIN from mobile app to the Issuer backend.

Conditional APIs

API

Inbound/Outbound

Description

Get PIN Change Counter API

Issuer <- Thales D1

In case of PIN Seccos. Used to retreive the PIN Change Counter needed for PIN Computation

SDK

Note
For enhanced security, the Change PIN API has a stricter default last login timeout period than the other APIs. To ensure successful PIN change, you have to manage the login/re-login flow to complete the login within the allocated time before submitting the PIN change.

@Nullable
@Override
public View onCreateView(
        @NonNull LayoutInflater inflater,
        @Nullable ViewGroup container,
        @Nullable Bundle savedInstanceState
) {
    View view = inflater.inflate(R.layout.fragment_main, container, false);

    SecureEditText entryEditPin = (SecureEditText)view.findViewById(R.id.pin_entry);
    SecureEditText confirmEditPin = (SecureEditText)view.findViewById(R.id.pin_confirm);
    PINEntryUI.PINEventListener listener = new PINEntryUI.PINEventListener() {
        @Override
        public void onPinEvent(PINEntryUI.PINEvent pinEvent, String additionalInfo) {
            switch (pinEvent){
                case FIRST_ENTRY_FINISH:
                    // switch focus to confirmEditPin
                    break;
                case PIN_MATCH:
                    // enable Continue/Submit button
                    break;
                case PIN_MISMATCH:
                    // disable Continue/Submit button and show error of PIN_MISMATCH
                    break;
            }
        }
    };

    String cardID = ""; // obtained e.g. from server
    ChangePINOptions options = new ChangePINOptions(4);
    pinEntryUI = d1Task.changePIN(cardID, entryEditPin, confirmEditPin, options, listener);

    Button button = (Button)view.findViewById(R.id.pin_submit);
    button.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View view) {
            pinEntryUI.submit(new D1Task.Callback<Void>() {
                @Override
                public void onSuccess(final Void data) {
                }

                @Override
                public void onError(@NonNull final D1Exception exception) {
                }
            });
        }
    });
    
    return view;
}

class ViewController: UIViewController {
    var pinEntryUI: PINEntryUI? = nil
    override func viewDidLoad() {
        let entryEditPin = D1SecureTextField()
        let confirmEditPin = D1SecureTextField()
        let cardID = "" // obtained e.g. from server
        let options = ChangePINOptions(pinLength: 4)
        pinEntryUI = d1Task.changePIN(cardID, textFieldNew: entryEditPin, textFieldConfirm: confirmEditPin, options: options, delegate: self)
    }

    func onButtonClick() {
        pinEntryUI?.submit { error in 
        }
    }
}

extension ViewController: PINEntryUIDelegate {
    func pinEntryUI(_ pinEntryUI: PINEntryUI, pinEvent: PINEntryUI.PINEvent, additionalInfo: String) {
        switch pinEvent {
            case .firstEntryFinish: 
                // switch focus to confirmEditPin
                break
            case .pinMismatch:
                // enable Continue/Submit button
                break
            case .pinMatch:
                // disable Continue/Submit button and show error of PIN_MISMATCH
                break
        }
    }
}

PreviousDisplay a PIN NextImplement card activation

Last updated 3 months ago

Was this helpful?

@Nullable
@Override
public View onCreateView(
        @NonNull LayoutInflater inflater,
        @Nullable ViewGroup container,
        @Nullable Bundle savedInstanceState
) {
    View view = inflater.inflate(R.layout.fragment_main, container, false);

    SecureEditText entryEditPin = (SecureEditText)view.findViewById(R.id.pin_entry);
    SecureEditText confirmEditPin = (SecureEditText)view.findViewById(R.id.pin_confirm);
    PINEntryUI.PINEventListener listener = new PINEntryUI.PINEventListener() {
        @Override
        public void onPinEvent(PINEntryUI.PINEvent pinEvent, String additionalInfo) {
            switch (pinEvent){
                case FIRST_ENTRY_FINISH:
                    // switch focus to confirmEditPin
                    break;
                case PIN_MATCH:
                    // enable Continue/Submit button
                    break;
                case PIN_MISMATCH:
                    // disable Continue/Submit button and show error of PIN_MISMATCH
                    break;
            }
        }
    };

    String cardID = ""; // obtained e.g. from server
    ChangePINOptions options = new ChangePINOptions(4);
    pinEntryUI = d1Task.changePIN(cardID, entryEditPin, confirmEditPin, options, listener);

    Button button = (Button)view.findViewById(R.id.pin_submit);
    button.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View view) {
            pinEntryUI.submit(new D1Task.Callback<Void>() {
                @Override
                public void onSuccess(final Void data) {
                }

                @Override
                public void onError(@NonNull final D1Exception exception) {
                }
            });
        }
    });
    
    return view;
}

class ViewController: UIViewController {
    var pinEntryUI: PINEntryUI? = nil
    override func viewDidLoad() {
        let entryEditPin = D1SecureTextField()
        let confirmEditPin = D1SecureTextField()
        let cardID = "" // obtained e.g. from server
        let options = ChangePINOptions(pinLength: 4)
        pinEntryUI = d1Task.changePIN(cardID, textFieldNew: entryEditPin, textFieldConfirm: confirmEditPin, options: options, delegate: self)
    }

    func onButtonClick() {
        pinEntryUI?.submit { error in 
        }
    }
}

extension ViewController: PINEntryUIDelegate {
    func pinEntryUI(_ pinEntryUI: PINEntryUI, pinEvent: PINEntryUI.PINEvent, additionalInfo: String) {
        switch pinEvent {
            case .firstEntryFinish: 
                // switch focus to confirmEditPin
                break
            case .pinMismatch:
                // enable Continue/Submit button
                break
            case .pinMatch:
                // disable Continue/Submit button and show error of PIN_MISMATCH
                break
        }
    }
}