Sign in
Encrypted PIN Change

Change card PIN with Change Request

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

  1. Retrieve the encryption key in JWK format with the GET Retrieve latest public key method and make it available.
  2. 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. 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. 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. Call this endpoint from your backend.
post/v1/cards/{card_account_id}/sca_pin_update_requests

Path parameters

card_account_idstring required

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

Request body

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.

Response

The request was accepted, and now the customer must confirm the change request.

idstring

ID of the change request.

status'ACCEPTED' | 'AUTHORIZATION_REQUIRED' | 'CONFIRMATION_REQUIRED' | 'COMPLETED' | 'FAILED'

The current status of the change request.

updated_atstring date-time

UTC timestamp from the last time the change request was updated.

urlstring

URL to use to authorize the change request.

Example response

{
  "id": "d6c778822b2d7bd3b778935bcfd0d1d3csc",
  "status": "CONFIRMATION_REQUIRED",
  "updated_at": "2022-04-21T13:59:52+00:00",
  "url": "https://example.com/authorize"
}