> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set PIN

> 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();




## OpenAPI

````yaml pin post /v3/set
openapi: 3.0.3
info:
  description: >
    Endpoint for viewing and setting PIN.


    There are three different methods for operating with card PIN:

    - Using a pre-shared 3DES key with Enfuce

    - Using public key cryptography (PKI)

    - Using the web view solution, described in the pincontrol API


    ## PCI compliance

    Processing PIN codes is controlled with strict compliance regulations by the
    card schemes. There are multiple ways to

    access the PIN in Enfuce's APIs depending on the client solution, and
    whether the client is a card schema member

    themselves and therefore responsible for compliance.


    The least complex way to take this functionality into use is to use the
    pincontrol API, since with that the entire 

    PIN transport mechanism is handled by Enfuce. Please see the pincontrol API
    documentation for this option.


    In the API described in this document, there are two solutions, a PKI
    approach, and a pre-shared key approach.


    The PKI approach, implemented correctly, will avoid exposing PIN codes to
    the client's back-end systems, but the

    PIN will still be processed by the card-holder device. This means that the
    software running on the device may need

    to be assessed for security and compliance.


    The pre-shared key approach will expose the PIN code to the client's
    back-end and can only be used by customers

    responsible for PIN handling towards the card scheme.
  version: '1'
  title: Card PIN API
  contact:
    name: Enfuce Financial Services
    url: https://enfuce.com
    email: info@enfuce.com
  x-logo:
    url: https://developer.enfuce.com/images/enfuce.svg
    altText: Enfuce logo
servers:
  - url: >-
      https://integration-api-cat1.{{environment}}.ext.{{realm}}.cia.enfuce.com/pin
  - url: https://integration-api-cat1.live.ext.prod.cia.enfuce.com/pin
    description: Live environment
security: []
tags:
  - name: PIN operations with pre-shared key
    description: >-
      <p>Endpoint for card PIN operations using pre-shared
      key.</p><p><strong>Note:</strong> If this endpoint is used, the client
      (that decrypts the PIN block and thus has access to the clear PIN) must be
      responsible for PIN handling towards the card scheme.</p>
  - name: PIN operations using PKI
    description: >-
      <p>Endpoint for Card PIN operations using public key
      cryptography.</p><p><strong>Note:</strong> If this endpoint is used, the
      client must make sure that the RSA key pair is generated and used by the
      card-holder device, giving no access to the private RSA key to any other
      system. This way, no other system will have any means to access the PIN
      code.</p>
paths:
  /v3/set:
    post:
      tags:
        - PIN operations using PKI
      summary: Set PIN
      description: >
        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();
      operationId: setPinPubKeyV3
      parameters:
        - name: auditUser
          in: query
          description: The audit user to log the request
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setPinRequest'
        description: The related PIN control request data
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setPinResponse'
        '401':
          $ref: '#/components/responses/error401'
        '403':
          $ref: '#/components/responses/error403'
        '404':
          $ref: '#/components/responses/controlIdNotFoundResponse'
        '500':
          $ref: '#/components/responses/error500'
components:
  schemas:
    setPinRequest:
      type: object
      properties:
        controlId:
          type: string
          description: Control ID received from PIN control API.
          example: 83fa5f55-3dd7-453a-8233-4242a6bad179
        pinBlock:
          type: string
          description: >-
            ISO format 1 PIN block 3DES encrypted with temporary PIN encryption
            key (tzpk). Base64-encoded.
          example: tACuB41yyfU=
      required:
        - controlId
        - pinBlock
      title: setPinRequest
    setPinResponse:
      type: object
      title: setPinResponse
    errorResponse:
      type: object
      properties:
        code:
          type: string
          description: An error code indicating what kind of error. I.e. HTTP error code
        message:
          type: string
          description: Error message in human-readable format
        id:
          type: string
          format: uuid
          description: Unique error identifier
        errorCode:
          type: string
          description: Enfuce code for a specific error type
        errorType:
          type: string
          description: Error type
          enum:
            - STATIC_VALIDATION_ERROR
            - DYNAMIC_VALIDATION_ERROR
            - INTEGRATION_ERROR
            - SECURITY_ERROR
            - UNEXPECTED_ERROR
        errorReason:
          type: string
          description: Free-form text explaining the error reason
        timestamp:
          type: string
          format: date-time
          description: Datetime when error occurred
  responses:
    error401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    controlIdNotFoundResponse:
      description: Control id does not exist or is expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    error500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'

````