swagger: '2.0'
info:
  description: 'The current set of APIs will be available in Q2 2026 on Worldline Global Issuing Platforms.

    Additional APIs are under construction and planned to be available in 2026.'
  version: 2.41.1
  title: Worldline Card Issuing Account - AccountState Card - CardPinState API
  contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Card - CardPinState
  description: Card Pin State
paths:
  /issuers/{issuerId}/cards/pin-state:
    post:
      tags:
      - Card - CardPinState
      summary: Card Pin State With EnquireCardStates
      operationId: getCardPinStateByCard
      description: "Operation which provides the currently effective details of the card entities matching the passed search criteria. \nSupported criteria are: Card reference or Card number or Alternative card number"
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        description: WL-Correlation-ID
        required: false
        type: string
      - name: WL-Username
        in: header
        required: false
        type: string
      - name: WL-Peer-ID
        in: header
        required: false
        type: string
      - in: body
        name: body
        description: body
        required: true
        schema:
          $ref: '#/definitions/RetrieveCardPinStateRequest'
      - name: issuerId
        in: path
        description: issuerId
        required: true
        type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntityCardPinState'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedResponseMetadata'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          schema:
            $ref: '#/definitions/BadGatewayErrorApiResponse'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/cards/pin-state/{accountReference}:
    get:
      tags:
      - Card - CardPinState
      summary: Card Pin State With EnquireCardStates
      operationId: getCardPinStateByAcctNbr
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        description: WL-Correlation-ID
        required: false
        type: string
      - name: WL-Username
        in: header
        required: false
        type: string
      - name: WL-Peer-ID
        in: header
        required: false
        type: string
      - name: accountReference
        in: path
        description: accountReference
        required: true
        type: string
      - name: issuerId
        in: path
        description: issuerId
        required: true
        type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntityCardPinStateList'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedResponseMetadata'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          schema:
            $ref: '#/definitions/BadGatewayErrorApiResponse'
      security:
      - basic: []
      deprecated: false
definitions:
  ApiResponseEntityCardPinState:
    type: object
    required:
    - responseMetadata
    properties:
      data:
        description: Response data
        allOf:
        - $ref: '#/definitions/CardStateResponse'
      responseMetadata:
        description: Response metadata
        allOf:
        - $ref: '#/definitions/ResponseMetadata'
    title: ApiResponseEntityCardPinState
    description: Issuer response entity
  ApiResponseEntityCardPinStateList:
    type: object
    required:
    - responseMetadata
    properties:
      data:
        type: array
        description: Response data
        items:
          $ref: '#/definitions/CardStateResponse'
      responseMetadata:
        $ref: '#/definitions/ResponseMetadata'
    title: ApiResponseEntityCardPinStateList
    description: Issuer response entity
  Links:
    type: object
    required:
    - self
    properties:
      self:
        type: string
        example: /x/{x}?x=x
        description: Service method URL
      next:
        type: string
        example: /x/{x}?page[offset]=2
        description: URL pagination query parameter next page
    title: Links
  NotFoundResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 404
        description: HTTP status code
      statusMessage:
        type: string
        example: Not found
        description: Executed REST API status message
    title: NotFoundResponseMetadata
  BadRequestResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 400
        description: HTTP status code
      statusMessage:
        type: string
        example: Bad request
        description: Executed REST API status message
    title: BadRequestResponseMetadata
  ResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      links:
        description: Metadata Links
        allOf:
        - $ref: '#/definitions/Links'
      statusMessage:
        type: string
        example: Executed successfully
        description: Executed REST API status message
      statusCode:
        type: integer
        format: int32
        example: 200
        description: HTTP status code
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      timeTakenMs:
        type: integer
        format: int64
        example: 12
        description: Wall clock time required from service to generate the response
    title: ResponseMetadata
  BadGatewayResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 502
        description: HTTP status code
      statusMessage:
        type: string
        example: Bad Gateway
        description: Executed REST API status message
    title: BadGatewayResponseMetadata
  CardStateResponse:
    type: object
    properties:
      accountReference:
        type: string
        description: 'DynamicReference

          minLength: 1

          maxLength: 100'
      alternativePan:
        type: string
        description: 'AlternativeCardNumber

          minLength: 1

          maxLength: 100'
      pan:
        type: string
        description: 'CardNumber

          minLength: 1

          maxLength: 28'
      cardReference:
        type: string
        description: 'DynamicReference

          minLength: 1

          maxLength: 100'
      maximumPinTryCounter:
        type: string
        description: "minimum: 0\nmaximum: 9999\nThe maximum amount of failed PIN tries which the cardholder can do. \nAfter that every PIN based transaction is declined until the PIN try counter is reset. \nNo matter whether the PIN is correct or not."
      nfcStatus:
        type: string
        description: "Indicates the status of the NFC antenna. \nPossible values are:\n- None (NFC antenna is not present)\n- Enabled (NFC antenna is enabled)\n- EnablingInProgress (Enabling of NFC antenna has been initiated but is not yet finished)\n- Disabled (NFC antenna is disabled)\n- DisablingInProgress (Disabling of NFC antenna has been initiated but is not yet finished)\n- Locked (NFC antenna is disabled for transport but will be automatically enabled by the card once the card is used)"
      nfcStatusChangeCounter:
        type: string
        description: 'minimum: 0

          maximum: 9999

          Number of changes performed on NfcStatus. Present in case NfcStatus is present.'
      nfcStatusChangeTime:
        type: string
        description: 'Example: 20200518235959

          Time of the last NfcStatus modification. Present in case NfcStatus is present.'
      offlinePinChangeStatus:
        type: string
        description: "Examples: List [ \"Pending\", \"InProgress\", \"Successful\", \"Failed\" ]\nIndicates the current status of adapting the offline PIN. \nPossible values are:\nPending (offline PIN needs to be changed but no script has been sent so far)\nInProgress (at least one PIN change script has been sent; receipt of a positive or negative confirmation is outstanding)\nSuccessful (offline PIN change finished successfully)\nFailed (offline PIN change did not finish successfully)"
      offlinePinChangeStatusChangeTime:
        type: string
        format: date-time
        description: 'Timestamp when the pinCheckParameterStatus was changed.

          Example: 2012-12-31T22:00:00.000'
      offlinePinChangeTryCounter:
        type: string
        description: "minimum: 0\nmaximum: 9999\nNumber of attempts to adapt the offline PIN, i.e. number of times a PIN change script has been sent in a response message. \nPresent in case OfflinePinChangeStatus is present."
      pinCheckParameter1:
        type: string
        description: 'minLength: 1

          maxLength: 64

          Depending on the used PIN verification method this field has different format and meaning:

          - IBM 3642 algorithm: PIN offset, decimal digits

          - German DK (Deutsche Kreditwirtschaft),: PRW (PIN-Referenzwert), 64 hexadecimal digits

          - German Proprietary: PRW (PIN-Referenzwert), 32 hexadecimal digits

          VISA: PVV, 4 decimal digits'
      pinCheckParameter2:
        type: string
        description: 'minLength: 1

          maxLength: 64

          Depending on the used PIN verification method this field has different format and meaning:

          - German DK (Deutsche Kreditwirtschaft): Random value, 8 hexadecimal digits

          - German Proprietary: PCC (PIN Change Counter), 4 decimal digits'
      pinCheckParameterStatus:
        type: string
        description: "Examples: List [ \"Active\", \"Blocked\" ]\nStatus of PIN check parameters. \nPossible values are:\nActive\nBlocked"
      pinCheckParameterStatusChangeTime:
        type: string
        format: date-time
        description: 'Timestamp when the OfflinePinChangeStatus was changed.

          Example: 2012-12-31T22:00:00.000'
      pinTryCounter:
        type: string
        description: 'minimum: 0

          maximum: 9999

          Number of failed PIN entries.'
      pinTryCounterChangeTime:
        type: string
        format: date-time
        description: 'Timestamp pattern: ^[0-9]{4}([0][1-9]|[1][012])(0[0-9]|[12][0-9]|3[01])(2[0-3]|[01][0-9])([0-5][0-9])([0-5][0-9])$|^$

          Example: 20200518235959'
      pinTryCounterResetTime:
        type: string
        format: date-time
        description: 'Timestamp pattern: ^[0-9]{4}([0][1-9]|[1][012])(0[0-9]|[12][0-9]|3[01])(2[0-3]|[01][0-9])([0-5][0-9])([0-5][0-9])$|^$

          Example: 20200518235959'
      pinTryCounterResetType:
        type: string
        description: 'Examples: List [ "Daily", "Fixed", "Never", "Other" ]

          Indicates the algorithm to reset the PIN try counter after exceeding the maximum number of allowed wrong entries.

          - Daily (Every day at a certain time)

          - Fixed (After expiry of a time interval)

          - Never (No automatic reset)'
      expiryDate:
        type: string
        description: 'The expiry date of the card

          Format is MMYY'
      status:
        type: string
        description: The status of the card
      blockingReason:
        type: string
        description: The reason why the card was blocked (if the card status is blocked)
    title: CardStates
  NotFoundErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/NotFoundResponseMetadata'
    title: NotFoundErrorApiResponse
  BadGatewayErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/BadGatewayResponseMetadata'
    title: BadGatewayErrorApiResponse
  InternalServerErrorErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/InternalServerErrorResponseMetadata'
    title: InternalServerErrorErrorApiResponse
  InternalServerErrorResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 500
        description: HTTP status code
      statusMessage:
        type: string
        example: Internal server error
        description: Executed REST API status message
    title: InternalServerErrorResponseMetadata
  ForbiddenErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/ForbiddenResponseMetadata'
    title: ForbiddenErrorApiResponse
  RetrieveCardPinStateRequest:
    description: One of cardNumber, alternativeCardNumber or cardReference is mandatory
    type: object
    properties:
      pan:
        type: string
        description: "minLength: 1\nmaxLength: 28\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
      alternativePan:
        type: string
        description: "minLength: 1\nmaxLength: 100\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
      cardReference:
        type: string
        description: "minLength: 1\nmaxLength: 100\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
    title: RetrieveCardPinStateRequest
  BadRequestErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/BadRequestResponseMetadata'
    title: BadRequestErrorApiResponse
  UnauthorizedResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 401
        description: HTTP status code
      statusMessage:
        type: string
        example: Unauthorized
        description: Executed REST API status message
    title: UnauthorizedResponseMetadata
  ForbiddenResponseMetadata:
    type: object
    required:
    - correlationId
    - responseDateTime
    - statusCode
    - statusMessage
    properties:
      correlationId:
        type: string
        description: Correlation Identifier
      responseDateTime:
        type: string
        example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
        description: Timestamp when response date was generated
      statusCode:
        type: integer
        format: int32
        example: 403
        description: HTTP status code
      statusMessage:
        type: string
        example: Forbidden
        description: Executed REST API status message
    title: ForbiddenResponseMetadata
securityDefinitions:
  basic:
    type: oauth2
    flow: application
    tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token