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 - Pin API
  contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Card - Pin
  description: Card Pin Api Controller
paths:
  /issuers/{issuerId}/cards/{cardReference}/display-pin:
    post:
      tags:
      - Card - Pin
      summary: Display PIN for a card
      operationId: displayPin
      description: "This service offers the option to the issuer to display the PIN inside the mobile app for a given card. \nThe card is identified either by the internal or external card reference.\nNote: Worldline will only send the PIN block towards the issuer. \nThe issuer is responsible for displaying the PIN inside the mobile app or Homebanking device."
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - name: cardReference
        in: path
        description: cardReference
        required: true
        type: string
      - in: body
        name: body
        required: false
        schema:
          $ref: '#/definitions/GetPinRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntityGetPinResponse'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/cards/{cardReference}/pin:
    post:
      tags:
      - Card - Pin
      summary: Set a PIN for a card
      operationId: setPin
      description: "This Service allows the issuer to set the PIN after card creation, via issuer home banking or mobile app. \nThe card is identified either by the internal or external card reference."
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - name: cardReference
        in: path
        description: cardReference
        required: true
        type: string
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/SetPinRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntitySetPinResponse'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/display-pin:
    post:
      tags:
      - Card - Pin
      summary: Display PIN for a card by external reference
      operationId: displayPinByIssuerExtRef
      description: "This service offers the option to the issuer to display the PIN inside the mobile app for a given card. \nThe card is identified either by the internal or external card reference.\nNote: Worldline will only send the PIN block towards the issuer. \nThe issuer is responsible for displaying the PIN inside the mobile app or Homebanking device."
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - name: issuerCardExternalReference
        in: path
        description: issuerCardExternalReference
        required: true
        type: string
      - in: body
        name: body
        required: false
        schema:
          $ref: '#/definitions/GetPinRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntityGetPinResponse'
      security:
      - basic: []
      deprecated: false
  /issuers/{issuerId}/cards/display-pin:
    post:
      tags:
      - Card - Pin
      summary: Display PIN for a card by PAN + PSN and/or expiry date
      operationId: displayPinByPan
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - in: body
        name: body
        required: false
        schema:
          $ref: '#/definitions/GetPinByPanRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/InternalServerErrorErrorApiResponse'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntityGetPinResponse'
      deprecated: false
  /issuers/{issuerId}/cards/pin:
    post:
      tags:
      - Card - Pin
      summary: Set a PIN for a card by PAN + PSN and/or expiry date
      operationId: setPinByPan
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/SetPinByPanRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/NotFoundErrorApiResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/InternalServerErrorErrorApiResponse'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntitySetPinResponse'
      deprecated: false
  /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/pin:
    post:
      tags:
      - Card - Pin
      summary: Set a PIN for a card by external reference
      operationId: setPinByIssuerExtRef
      description: "This Service allows the issuer to set the PIN after card creation, via issuer home banking or mobile app. \nThe card is identified either by the internal or external card reference."
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        type: string
      - name: issuerCardExternalReference
        in: path
        description: issuerCardExternalReference
        required: true
        type: string
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/SetPinRequest'
      responses:
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ApiResponseEntitySetPinResponse'
      security:
      - basic: []
      deprecated: false
definitions:
  CardIdentifier:
    type: object
    description: Identification of the card either by Issuer card external reference or by card reference
    properties:
      cardReference:
        type: string
        description: 'Reference of the card generated by our system, unique per platform.

          This reference is calculated sequentially by an internal algorithm on 16 digits (e.g. 2000000000096013).'
      issuerCardExternalReference:
        type: string
        description: 'External reference of the card provided by the issuer or calculated by the system if the external reference generation algorithm is configured for the issuer.

          This reference is unique per issuer and may be used to carry out research and find information.'
    title: CardIdentifier
  SetPinRequest:
    type: object
    required:
    - pinAttribute
    properties:
      event:
        type: string
        description: EXTERNAL (default), INTERNAL, ATM or IVR
      panExpiryDate:
        type: string
        description: Format MMYY
      pinAttribute:
        $ref: '#/definitions/PinAttribute'
    title: SetPinRequest
  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
  UnauthorizedErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/UnauthorizedResponseMetadata'
    title: UnauthorizedResponseMetadata
  ApiResponseEntitySetPinResponse:
    type: object
    required:
    - responseMetadata
    properties:
      data:
        description: Response data
        allOf:
        - $ref: '#/definitions/SetPinResponse'
      responseMetadata:
        description: Response metadata
        allOf:
        - $ref: '#/definitions/ResponseMetadata'
    title: ApiResponseEntitySetPinResponse
    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
  GetPinRequest:
    type: object
    description: encryptedSessionKey is the encrypted session key to be used for encrypting the PIN in the reply
    properties:
      event:
        type: string
        description: EXTERNAL (default), INTERNAL, ATM or IVR
      encryptedSessionKey:
        $ref: '#/definitions/EncryptedData'
    title: GetPinRequest
  GetPinResponse:
    type: object
    required:
    - externalPinAttribute
    properties:
      cardIdentifier:
        $ref: '#/definitions/CardIdentifier'
      externalPinAttribute:
        $ref: '#/definitions/PinAttribute'
    title: GetPinResponse
  SetPinByPanRequest:
    type: object
    required:
    - pinAttribute
    properties:
      event:
        type: string
        description: EXTERNAL (default -> just don't mention the field), INTERNAL, ATM or IVR
      pinAttribute:
        $ref: '#/definitions/PinAttribute'
      encryptedPan:
        $ref: '#/definitions/EncryptedPanData'
      pan:
        type: string
        description: Either encryptedPan or pan should be mentioned
      panSequenceNumber:
        type: string
        description: Either panSequenceNumber or panExpiryDate should be mentioned, or both
      panExpiryDate:
        type: string
        description: Format MMYY - Either panSequenceNumber or panExpiryDate should be mentioned, or both
      encryptedPinBlockPan:
        $ref: '#/definitions/EncryptedPanData'
      pinBlockPan:
        type: string
        description: Only for cases where PAN input to PIN block computation should be overriden; either encryptedPinBlockPan or pinBlockPan should be mentioned
    title: SetPinByPanRequest
  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
  EncryptedData:
    type: object
    required:
    - algoId
    - encryptedData
    - keyId
    properties:
      algoId:
        type: string
        description: 'Algorithm used to encrypt Session Key

          Allowed Value:

          06 for RSA'
      encryptedData:
        type: string
        description: Cryptogram in hexadecimal string representation
      keyId:
        type: string
        description: 'Key set used for request

          Allowed Value:

          01 - Keyset1

          02 - Keyset2'
    title: EncryptedData
  GetPinByPanRequest:
    type: object
    description: encryptedSessionKey is the encrypted session key to be used for encrypting the PIN in the reply
    properties:
      event:
        type: string
        description: EXTERNAL (default -> just don't mention the field), INTERNAL, ATM or IVR
      encryptedSessionKey:
        $ref: '#/definitions/EncryptedData'
      encryptedPan:
        $ref: '#/definitions/EncryptedPanData'
      pan:
        type: string
        description: Either encryptedPan or pan should be mentioned
      panSequenceNumber:
        type: string
        description: Either panSequenceNumber or panExpiryDate should be mentioned, or both
      panExpiryDate:
        type: string
        description: Format MMYY - Either panSequenceNumber or panExpiryDate should be mentioned, or both
      encryptedPinBlockPan:
        $ref: '#/definitions/EncryptedPanData'
      pinBlockPan:
        type: string
        description: Only for cases where PAN input to PIN block computation should be overriden; either encryptedPinBlockPan or pinBlockPan should be mentioned
    title: GetPinByPanRequest
  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
  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
  EncryptedPanData:
    type: object
    required:
    - algoId
    - encryptedData
    - keyId
    properties:
      algoId:
        type: string
        description: 00 = PCI-AES, 01 = BEST, 02 = PCI-PAN, 03 = AES-GCM, 11 = PCI-TDES
      encryptedData:
        type: string
        description: Cryptogram in hexadecimal string representation
      keyId:
        type: string
        description: Either PCI hexadecimal key index or 01 for BEST/AES-GCM keyset 1 or 02 for BEST/AES-GCM keyset 2
      sessionKey:
        type: string
        description: BEST session key in hexadecimal string representation
      initializationVector:
        type: string
        description: BEST or AES-GCM initialization vector in hexadecimal string representation
      authenticationTag:
        type: string
        description: AES-GCM authentication tag in hexadecimal string representation
    title: EncryptedPanData
  ApiResponseEntityGetPinResponse:
    type: object
    required:
    - responseMetadata
    properties:
      data:
        description: Response data
        allOf:
        - $ref: '#/definitions/GetPinResponse'
      responseMetadata:
        description: Response metadata
        allOf:
        - $ref: '#/definitions/ResponseMetadata'
    title: ApiResponseEntityGetPinResponse
    description: Issuer response entity
  ForbiddenErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/ForbiddenResponseMetadata'
    title: ForbiddenErrorApiResponse
  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
  SetPinResponse:
    type: object
    description: pinAttribute is just an echo of the input PIN
    properties:
      pinAttribute:
        $ref: '#/definitions/PinAttribute'
    title: SetPinResponse
  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
  PinAttribute:
    type: object
    required:
    - pinAlgorithmId
    - pinBlock
    - pinBlockFormat
    properties:
      encryptedSessionKey:
        $ref: '#/definitions/EncryptedData'
      key:
        type: string
        description: Not used
      keyId:
        type: string
        description: 'Key set used for response

          Allowed Value:

          01 - Keyset1

          02 - Keyset2'
      pinAlgorithmId:
        type: string
        description: 'Algorithm used to encrypt the PIN

          Allowed Value:

          04 = ISO-4 (=> encryptedSessionKey required)

          05 = ISO-1-BAPOF (internal transport + BE banks)

          06 = RSA-APAC (deprecated)

          07 = BEST-PIN (internal migration)'
      pinBlock:
        type: string
        description: PIN block in hexadecimal string representation
      pinBlockFormat:
        type: string
        description: ISO-4, ISO-1-BAPOF, RSA-APAC, BEST-PIN, etc. (free text, no strict constraint)
    title: PinAttribute
  BadRequestErrorApiResponse:
    type: object
    required:
    - responseMetadata
    properties:
      responseMetadata:
        allOf:
        - $ref: '#/definitions/BadRequestResponseMetadata'
    title: BadRequestErrorApiResponse
  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