> ## 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.

> This operation sets PIN with encrypted PIN block in ISO format 1. The PIN block is encrypted using a pre-shared\ndouble-length 3DES key.

# Set PIN

### Example

```
// PIN 1234 in ISO format 1
var pinBlock = "141234AAAAAAAAAA";
// pre-shared zpk
var zpk = Hex.decode("00112233445566778899AABBCCDDEEFF0011223344556677");
// encrypt pinBlock with zpk
var des = Cipher.getInstance("DESede/ECB/NoPadding");
des.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(zpk, "DESede"));
var encryptedPinBlock = Hex.toHexString(des.doFinal(Hex.decode(pinBlock)));
// make request
pinApiClient.post()
        .uri("/pin/v2/{plasticId}?auditUser={user}", 123456, "test")
        .bodyValue(Map.of(
                "zpkIndex", "0",
                "pinBlock", encryptedPinBlock
        ))
        .retrieve()
        .bodyToMono(Object.class)
        .block();
```


## OpenAPI

````yaml pin post /v2/{plasticId}
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:
  /v2/{plasticId}:
    post:
      tags:
        - PIN operations with pre-shared key
      summary: Set PIN
      description: >
        This operation sets PIN with encrypted PIN block in ISO format 1. The
        PIN block is encrypted using a pre-shared

        double-length 3DES key.


        #### Example
            // PIN 1234 in ISO format 1
            var pinBlock = "141234AAAAAAAAAA";
            // pre-shared zpk
            var zpk = Hex.decode("00112233445566778899AABBCCDDEEFF0011223344556677");
            // encrypt pinBlock with zpk
            var des = Cipher.getInstance("DESede/ECB/NoPadding");
            des.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(zpk, "DESede"));
            var encryptedPinBlock = Hex.toHexString(des.doFinal(Hex.decode(pinBlock)));
            // make request
            pinApiClient.post()
                    .uri("/pin/v2/{plasticId}?auditUser={user}", 123456, "test")
                    .bodyValue(Map.of(
                            "zpkIndex", "0",
                            "pinBlock", encryptedPinBlock
                    ))
                    .retrieve()
                    .bodyToMono(Object.class)
                    .block();
      operationId: setPINV2usingPOST
      parameters:
        - name: auditUser
          in: query
          description: The audit user to log the request
          required: true
          schema:
            type: string
        - name: plasticId
          in: path
          description: The plastic id for given card
          required: true
          schema:
            type: string
            format: biginteger
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pinBlockRequest'
        description: The related PIN control request data
        required: true
      responses:
        '200':
          description: PIN set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setPinResponse'
        '401':
          $ref: '#/components/responses/error401'
        '403':
          $ref: '#/components/responses/error403'
        '404':
          $ref: '#/components/responses/cardNotFoundResponse'
        '500':
          $ref: '#/components/responses/error500'
components:
  schemas:
    pinBlockRequest:
      type: object
      properties:
        zpkIndex:
          type: string
          description: >
            The PIN encryption key (ZPK) index. This index is used to point out
            which key to use in case there are

            multiple keys available.
          example: '0'
        pinBlock:
          type: string
          description: >-
            ISO format 1 PIN block 3DES encrypted with PIN encryption key in
            hexadecimal.
          example: 0123456789ABCDEF
          minLength: 16
          maxLength: 16
      required:
        - zpkIndex
        - pinBlock
      title: pinBlockRequest
    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'
    cardNotFoundResponse:
      description: Card does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    error500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'

````