Encrypted PIN Change

Change card PIN

Changes the PIN of the card specified in the request URL. Follow these instructions to use this endpoint:

  1. In your backend, retrieve the encryption key in JWK format with the GET Retrieve latest public key method and make it available to the customer's device.
  2. On the customer's device, collect the customer's desired PIN through a text input in your frontend and store it as string containing a JSON-formatted object {"pin": "<NEW_PIN>"}.
  3. On the customer's device, parse the received encryption key JWK from the first step (you may want to use a suitable library of your choice, e.g. JOSESwift for iOS or Nimbus JOSE for Android).
  4. On the customer's device, encrypt the string containing the new PIN from step 2 into a JWE using the previously received encryption key and the following properties:
    1. Algorithm: RSA-OAEP-256
    2. Encryption method: A256CBC-HS512
    3. Key ID: kid property from the encryption key JWK
  5. On the customer's device, generate the compact serialization of the JWE created in the previous step—this will be used as the encrypted_pin parameter.
  6. On the customer's device, sign the serialized JWE of the previous step using the cardholder's private key from their bound device — this is the signature parameter. Note that you must use the restricted key.
  7. Transfer the values generated in the previous two steps (serialized JWE and created signature) to your backend.
  8. Call this endpoint from your backend.
post/v1/cards/{card_account_id}/pin_update_requests

Path parameters

card_account_idstring required

Unique identifier of the card whose PIN you wish to change.

Request body

device_idstring required

ID of the customer's previously bound device.

device_datastring

Encoded device fingerprint generated using the Seon SDK. See the device monitoring guide for more information about generating this value.

encrypted_pinstring required

The encrypted PIN value (JWE in compact serialization). See the description of this method for instructions on how to produce this value.

key_idstring required

Solaris' public RSA key ID. Returned as the kid property by the GET Retrieve latest public key endpoint.

signaturestring required

The signature of the encrypted_pin created with the device binding key.

Response

The card's PIN was successfully changed.