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

Sample PIN change screen in the Issuer Application

Flow

High-level flow to change a PIN

1. The user authenticates on the banking app and request to change the PIN
2. An internal call is made to the SDK
3. Capture securely the PIN
4. D1 BackEnd API
5. D1 transciphers the PIN from device key to Issuer key
6. 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.

Sequence diagram for PIN change

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.

Android

@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;
}

iOS

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
        }
    }
}