openapi: 3.0.0
info:
  title: Outbound PIN Management API
  version: '1.0'
  description: PIN Management API to be supported by the Issuer Backend
  contact:
    name: Thales Support
    url: https://www.thalesgroup.com/en/markets/digital-identity-and-security
    email: thalessupport@thalesgroup.com
servers:
  - url: https://YOUR_DOMAIN_NAME
    description: Production server
  - url: https://YOUR_DOMAIN_NAME
    description: Staging server
security:
  - bearerAuth: []
tags:
  - name: PIN Management
    description: PIN Management APIs
paths:
  /cms/api/v1/issuers/{issuerId}/cards/{cardId}/pin:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/card-id-path'
      - $ref: '#/components/parameters/x-correlation-id-output'
    put:
      summary: Set Card PIN
      operationId: SetPIN
      requestBody:
        $ref: '#/components/requestBodies/SetPinRequestBody'
      responses:
        '204':
          description: PIN set successfuly
        '400':
          $ref: '#/components/responses/BadRequestOutbound'
        '401':
          $ref: '#/components/responses/UnauthorizedOutbound'
        '403':
          $ref: '#/components/responses/ForbiddenForPhysicalCardOutbound'
        '404':
          $ref: '#/components/responses/NotFoundForPhysicalCardOutbound'
        '500':
          $ref: '#/components/responses/InternalServerErrorOutbound'
      description: This request is used by D1 to push securelly in core banking system the PIN value for a physical card.
    get:
      summary: Get Card PIN
      operationId: getPIN
      responses:
        '200':
          $ref: '#/components/responses/GetPinResponseBody'
        '400':
          $ref: '#/components/responses/BadRequestOutbound'
        '401':
          $ref: '#/components/responses/UnauthorizedOutbound'
        '403':
          $ref: '#/components/responses/ForbiddenForPhysicalCardOutbound'
        '404':
          $ref: '#/components/responses/NotFoundForPhysicalCardOutbound'
        '500':
          $ref: '#/components/responses/InternalServerErrorOutbound'
      description: This request is used by D1 to retrieve the PIN value of a physical card.
  /cms/api/v1/issuers/{issuerId}/cards/{cardId}/pin/changeCounter:
    parameters:
      - $ref: '#/components/parameters/issuer-id-path'
      - $ref: '#/components/parameters/card-id-path'
      - $ref: '#/components/parameters/x-correlation-id-output'
    get:
      summary: Get PIN Change Counter
      operationId: getPINChangeCounter
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  pcc:
                    type: string
                    description: The PIN Change Counter value.
                    pattern: ^[0-9]{4}$
                    example: '0003'
                  intdatag:
                    type: string
                    description: |
                      Identifier used to correlate the call to get Pin Change Counter and the call to set Pin.
                    minLength: 20
                    maxLength: 20
                    example: '21430919092023091909'
                required:
                  - pcc
                  - intdatag
        '400':
          $ref: '#/components/responses/BadRequestOutbound'
        '401':
          $ref: '#/components/responses/UnauthorizedOutbound'
        '403':
          $ref: '#/components/responses/ForbiddenForGetPinChangeCounter'
        '404':
          $ref: '#/components/responses/NotFoundForPhysicalCardOutbound'
        '500':
          $ref: '#/components/responses/InternalServerErrorOutbound'
      description: |
        API used by D1 retreive from Issuer Backend the PIN Change Counter for a given card.
        <br/>The PIN Change counter is used to compute PRW and MAC
      parameters: []
components:
  requestBodies:
    SetPinRequestBody:
      description: Request body for setting the card PIN
      content:
        application/json:
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/setPinBlock'
  schemas:
    setPinBlock:
      required:
        - type
        - encryptedPinBlock
      properties:
        type:
          type: string
          description: The type of the PIN Block.
          enum:
            - ISO0
            - 3DES_SECCOS
        encryptedPinBlock:
          type: string
          maxLength: 8192
          description: |
            The value is the encrypted json (cf http://www.json.org/ ) representation of the PIN Block.
            <br/>This value is encrypted using the JWE encryption (please refer to the **[Sensitive Information Encryption](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)
            |Schemas of the PIN Block once decrypted|
            |-------|
            |[PIN Block ISO0](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESISO0)|
            |[PIN Block 3DES Seccos](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESSECCOS)|
      title: Set PIN Block
      discriminator:
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/pinblock3DESISO0'
        - $ref: '#/components/schemas/pinblock3DESSECCOS'
    getPinBlock:
      required:
        - type
        - encryptedPinBlock
      properties:
        type:
          type: string
          description: The type of the PIN Block.
          enum:
            - ISO0
        encryptedPinBlock:
          type: string
          maxLength: 8192
          description: |
            The value is the encrypted json (cf http://www.json.org/ ) representation of the PIN Block.
            <br/>This value is encrypted using the JWE encryption (please refer to the **[Sensitive Information Encryption](../../../integrate-the-d1-api/encrypt-sensitive-data)** for more details)
            |Schemas of the PIN Block once decrypted|
            |-------|
            |[PIN Block ISO0](reference/D1-Public-OUT-v1-PIN-Management.oas3.yml/components/schemas/pinblock3DESISO0)|
      title: Get PIN Block
      discriminator:
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/pinblock3DESISO0'
    pinblock3DESISO0:
      title: PIN 3DES ISO0
      type: object
      properties:
        pinValue:
          type: string
          maxLength: 8192
          description: |
            The PIN in format ISO0 encrypted under 3DES Key.
        kid:
          type: string
          maxLength: 128
          example: DIGIBANK01.LIVE.PIN.PEK.01
          description: |
            The key label or identifier of the 3DES key used to encrypt the PIN Block.
    pinblock3DESSECCOS:
      title: PIN 3DES SECCOS
      type: object
      properties:
        intdatag:
          type: string
          minLength: 20
          maxLength: 20
          example: '21430919092023091909'
          description: |
            Identifier used to correlate the call to get Pin Change Counter and the call to set Pin.
        prwDataSet:
          type: string
          pattern: '[0-9A-F]{246}'
          description: |
            The data used to compute the PIN Reference Value (PRW) without sensitive data (pan replaced by 00...00).
        prwValue:
          type: string
          maxLength: 64
          description: |
            The PIN Reference Value (PRW).
        prwKid:
          type: string
          maxLength: 128
          example: DIGIBANK01.LIVE.PIN.PEK.01
          description: |
            The key label or identifier of the key used to compute the PIN Reference value
        macValue:
          type: string
          maxLength: 16
          description: |
            The PRW Mac value.
        macKid:
          type: string
          maxLength: 128
          example: DIGIBANK01.LIVE.SECCOSMAC.KMAC.01
          description: |
            The index of the key used to compute the MAC
    issuerId:
      maxLength: 10
      minLength: 10
      type: string
    cardId:
      type: string
      description: Unique identifier of the card.
      minLength: 1
      maxLength: 48
      pattern: ^[A-Za-z0-9_-]{1,48}$
    errorGenericOutbound:
      type: object
      description: Generic error returned by the APIs.
      properties:
        error:
          type: string
          description: Description of the error.
          example: Card does not exist
    errorCodeWithError:
      type: object
      description: The error code and message corresponding to reason of failure.
      properties:
        errorCode:
          type: string
          enum:
            - PIN_CHANGE_FORBIDDEN
            - CARD_NOT_ACTIVE
        error:
          type: string
          description: Description of the error.
          example: Pin Change is not allowed for this card
  responses:
    GetPinResponseBody:
      description: |
        The response body to get PIN to be displayed. This value is encrypted using the JWE encryption
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getPinBlock'
    BadRequestOutbound:
      description: Bad Request, Invalid request URI or header, or unsupported non-standard parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorGenericOutbound'
    UnauthorizedOutbound:
      description: The provided Authorization header is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorGenericOutbound'
    ForbiddenForPhysicalCardOutbound:
      description: Forbidden action, check the state of the linked end user (consumer) or account or card
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorGenericOutbound'
    NotFoundForPhysicalCardOutbound:
      description: Resource not found, Unknown issuerId or consumerId or accountId or card id
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorGenericOutbound'
    InternalServerErrorOutbound:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorGenericOutbound'
    ForbiddenForGetPinChangeCounter:
      description: Forbidden action, check the state of the linked consumer or account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorCodeWithError'
  securitySchemes:
    bearerAuth:
      type: http
      description: A JWT generated by the [Get Authorization Token API](oauth2-api).<br/>The server checks the validity of the provided token to control access to this protected resource. Please refer to [Get OAuth 2.0 access token](../../../integrate-the-d1-api/get-oauth-2.0-access-token) for more details on the flow and on how to get this JWT.
      scheme: bearer
      bearerFormat: JWT
  parameters:
    issuer-id-path:
      description: The id of the issuer
      in: path
      name: issuerId
      required: true
      schema:
        $ref: '#/components/schemas/issuerId'
    card-id-path:
      description: The id of the card
      in: path
      name: cardId
      required: true
      schema:
        $ref: '#/components/schemas/cardId'
    x-correlation-id-output:
      description: |-
        Random identifier which can be used to correlate the different API calls done as part of a single use-case. This identifier will be the one primarily used for troubleshooting.

        There is no strong guarantee of the uniqueness of this identifier, so please refrain from using it for other purpose than logging and troubleshooting.
      in: header
      name: x-correlation-id
      schema:
        type: string
