Worldline Card - CardPinState API

openapi: 3.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 Card - CardPinState API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
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"
      parameters:
      - name: WL-Correlation-ID
        in: header
        description: WL-Correlation-ID
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: WL-Peer-ID
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCardPinState'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponseMetadata'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveCardPinStateRequest'
        description: body
        required: true
  /issuers/{issuerId}/cards/pin-state/{accountReference}:
    get:
      tags:
      - Card - CardPinState
      summary: Card Pin State With EnquireCardStates
      operationId: getCardPinStateByAcctNbr
      parameters:
      - name: WL-Correlation-ID
        in: header
        description: WL-Correlation-ID
        required: false
        schema:
          type: string
      - name: WL-Username
        in: header
        required: false
        schema:
          type: string
      - name: WL-Peer-ID
        in: header
        required: false
        schema:
          type: string
      - name: accountReference
        in: path
        description: accountReference
        required: true
        schema:
          type: string
      - name: issuerId
        in: path
        description: issuerId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityCardPinStateList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponseMetadata'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorApiResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorErrorApiResponse'
        '502':
          description: Bad gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadGatewayErrorApiResponse'
      security:
      - basic: []
      deprecated: false
components:
  schemas:
    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
    InternalServerErrorErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/InternalServerErrorResponseMetadata'
      title: InternalServerErrorErrorApiResponse
    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
    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
    ResponseMetadata:
      type: object
      required:
      - correlationId
      - responseDateTime
      - statusCode
      - statusMessage
      properties:
        correlationId:
          type: string
          description: Correlation Identifier
        links:
          description: Metadata Links
          allOf:
          - $ref: '#/components/schemas/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
    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
    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
    ApiResponseEntityCardPinStateList:
      type: object
      required:
      - responseMetadata
      properties:
        data:
          type: array
          description: Response data
          items:
            $ref: '#/components/schemas/CardStateResponse'
        responseMetadata:
          $ref: '#/components/schemas/ResponseMetadata'
      title: ApiResponseEntityCardPinStateList
      description: Issuer response entity
    BadRequestErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadRequestResponseMetadata'
      title: BadRequestErrorApiResponse
    ApiResponseEntityCardPinState:
      type: object
      required:
      - responseMetadata
      properties:
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/CardStateResponse'
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
      title: ApiResponseEntityCardPinState
      description: Issuer response entity
    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
    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
    NotFoundErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/NotFoundResponseMetadata'
      title: NotFoundErrorApiResponse
    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
    ForbiddenErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/ForbiddenResponseMetadata'
      title: ForbiddenErrorApiResponse
    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
    BadGatewayErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadGatewayResponseMetadata'
      title: BadGatewayErrorApiResponse
  securitySchemes:
    basic:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token