{
  "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"
        }
      ],
      "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"
        }
      ],
      "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.\n",
                      "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.\n<br/>The PIN Change counter is used to compute PRW and MAC\n",
        "parameters": []
      }
    }
  },
  "components": {
    "requestBodies": {
      "SetPinRequestBody": {
        "description": "Request body for setting the card PIN",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/setPinBlock"
            }
          }
        }
      }
    },
    "schemas": {
      "setPinBlock": {
        "type": "object",
        "required": [
          "type",
          "encryptedPinBlock"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of the PIN Block.",
            "enum": [
              "ISO0",
              "3DES_SECCOS"
            ]
          },
          "encryptedPinBlock": {
            "type": "string",
            "maxLength": 8192,
            "example": "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6IkFTRHNMLUp4MlhPa1JuRnRxVy1RYmxXWS1tRG5RVzJMZ2FwYWRGeDc1dEEiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJpb1VsOHpVbG41MDY0am9ZUnNBdUVPZmhiR1lUcGVqaVBVTVJiT183OEx3IiwieSI6IjhvR1VZUTdGZjVHeVl2TUlPQ3M2alg2dE4yUGFyMlJLRTlPX2NRbG9mVk0ifX0..AXz2wwr2cStQZNx5.t0Z2TzJir25lGMZEyUi7IJx7.TkUbBIqVr_8KH20ZyUM9Nw",
            "description": "JWE encrypted PIN object containing PIN Value and Key version.\n\nSee \"PIN Block ISO0\" or \"PIN Block 3DES Seccos\" to get the PIN structure once decrypted\n"
          }
        },
        "title": "Set PIN Block"
      },
      "getPinBlock": {
        "type": "object",
        "required": [
          "type",
          "encryptedPinBlock"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of the PIN Block.",
            "enum": [
              "ISO0"
            ]
          },
          "encryptedPinBlock": {
            "type": "string",
            "maxLength": 8192,
            "example": "eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6IkFTRHNMLUp4MlhPa1JuRnRxVy1RYmxXWS1tRG5RVzJMZ2FwYWRGeDc1dEEiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJpb1VsOHpVbG41MDY0am9ZUnNBdUVPZmhiR1lUcGVqaVBVTVJiT183OEx3IiwieSI6IjhvR1VZUTdGZjVHeVl2TUlPQ3M2alg2dE4yUGFyMlJLRTlPX2NRbG9mVk0ifX0..AXz2wwr2cStQZNx5.t0Z2TzJir25lGMZEyUi7IJx7.TkUbBIqVr_8KH20ZyUM9Nw",
            "description": "JWE encrypted PIN object containing PIN Value and Key version.\n\nSee \"PIN Block ISO0\" to get the PIN structure once decrypted\n"
          }
        },
        "title": "Get PIN Block"
      },
      "pinblock3DESISO0": {
        "title": "PIN 3DES ISO0",
        "type": "object",
        "properties": {
          "pinValue": {
            "type": "string",
            "maxLength": 8192,
            "description": "The PIN in format ISO0 encrypted under 3DES Key.\n"
          },
          "kid": {
            "type": "string",
            "maxLength": 128,
            "example": 1,
            "description": "The version of the 3DES key used to encrypt the PIN.\n"
          }
        }
      },
      "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.\n"
          },
          "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).\n"
          },
          "prwValue": {
            "type": "string",
            "maxLength": 64,
            "description": "The PIN Reference Value (PRW).\n"
          },
          "prwKid": {
            "type": "string",
            "maxLength": 128,
            "example": 1,
            "description": "The version of the key used to compute the PIN Reference value\n"
          },
          "macValue": {
            "type": "string",
            "maxLength": 16,
            "description": "The PRW Mac value.\n"
          },
          "macKid": {
            "type": "string",
            "maxLength": 128,
            "example": 1,
            "description": "The version of the key used to compute the MAC\n"
          }
        }
      },
      "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\n",
        "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": {
        "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.\n\nThere 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"
        }
      }
    }
  }
}