---
title: "Set PIN"
method: POST
path: "/v3/set"
tags: ["PIN operations using PKI"]
---

# Set PIN

`POST /v3/set`

This operation sets the card PIN. Provided PIN must be in ISO format 1 and encrypted with the tzpk
received from the "Get tzpk" API call.

### Example flow
#### Step 1, executed on the CARD-HOLDER DEVICE, encrypting the PIN block with the TZPK
    // PIN 1234 in ISO format 1 (xxYYYYxxxxxxxxxx) where YYYY is the PIN
    var pinBlock = "141234AAAAAAAAAA";
    // encrypt pinBlock with previously received tzpk
    var des = Cipher.getInstance("DESede/ECB/NoPadding");
    des.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(tzpk, "DESede"));
    var encryptedPinBlock = des.doFinal(Hex.decode(pinBlock.getBytes()));

#### Step 2, executed on the CLIENT BACK-END, sending the encrypted PIN block recieved from the device, to the API
    // var encryptedPinBlock = // Received from the device
    // make request
    pinApiClient.post()
            .uri("/pin/v3/set?auditUser={user}", "test")
            .bodyValue(Map.of(
                    "controlId", controlId,
                    "pinBlock", Base64.getEncoder().encodeToString(encryptedPinBlock)
            ))
            .retrieve()
            .bodyToMono(Object.class)
            .block();

## Query parameters

- `auditUser` string, required

## Request body

- SetPinRequest
  - `controlId` string, required — Control ID received from PIN control API.
  - `pinBlock` string, required — ISO format 1 PIN block 3DES encrypted with temporary PIN encryption key (tzpk). Base64-encoded.

## Response `200`

- SetPinResponse

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Control id does not exist or is expired
- `500` — Internal server error

---

[API](https://skmtc.net/enfuce/apis/transfer-api.md) · [All operations](https://skmtc.net/enfuce/apis/transfer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/enfuce/transfer-api/revisions/dc4a41118f80/schema)