Skip to content
/
Encrypted PIN change
Last updated

Encrypted PIN change

Solaris provides a set of secure, encrypted endpoints for changing the PIN for your customers' cards. This page explains how to implement this process in your solution.

Prerequisites

There are two methods for changing a customer's PIN using your solution:

  1. Encrypted PIN change via Device binding.
  2. Encrypted PIN change via Change request.

Implement the respective feature(s) in your solution depending on what you wish to offer your customers. If you use the device signing method for PIN change, your customer's device must have already generated a private and public key pair before you can use the PIN change endpoints.

PIN requirements

  • The PIN must be exactly 4 numerical digits (i.e., 0123456789).
  • The digits may not be sequential in any order (e.g., 1234 or 4321).
  • A single digit may not repeat 3 or more times (e.g., 1111 or 1112).
  • PINs cannot be changed at ATMs, even if the ATM presents this option.

Implementation steps

Follow the instructions in the API documentation for the respective PIN change methods:

Code examples

The following examples demonstrate how to implement the encryption flow.

@Getter
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
class PinKey {
    String kid;
    String kty;
    String use;
    String alg;
    String n;
    String e;
}
 
@Getter
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
class UpdatePinRequest {
    String encrypted_data;
    String id;
    String signature;
    String device_id;
}
 
private void solarisbank_pin_change_integration()  {
 
        //    STEP 1
        PinKey pin_key = client.get("/v1/cards/1234567mcrd/pin_keys/latest");
 
        //    STEP 2
        String payload_to_encrypt = "{\"pin\":\"1928\"}";
 
 
        //    STEP 3
        RSAPublicKey solaris_public_key = JWK.parse(new ObjectMapper().writeValueAsString(pin_key))
                .toRSAKey()
                .toRSAPublicKey();
 
        //    STEP 4
        JWEHeader jweHeader = new JWEHeader
                .Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256CBC_HS512)
                .build();
 
        JWEObject jweObject = new JWEObject(jweHeader, new Payload(payload_to_encrypt));
        jweObject.encrypt(new RSAEncrypter(solaris_public_key));
        String encrypted_data = jweObject.serialize();
         
        //    STEP 5
        String signature = extract_signature(encrypted_data);
 
        //    STEP 6
        client.post("/v1/cards/1234567mcrd/pin_update_requests", new UpdatePinRequest(encrypted_data, pin_key.getKid(), signature, device_id));
    }
Previous page
Next page