Worldline Card - Pin 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 - Pin API
  contact: {}
servers:
- url: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing/api/v2
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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: cardReference
        in: path
        description: cardReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityGetPinResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPinRequest'
  /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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: cardReference
        in: path
        description: cardReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntitySetPinResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPinRequest'
        required: true
  /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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCardExternalReference
        in: path
        description: issuerCardExternalReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityGetPinResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPinRequest'
  /issuers/{issuerId}/cards/display-pin:
    post:
      tags:
      - Card - Pin
      summary: Display PIN for a card by PAN + PSN and/or expiry date
      operationId: displayPinByPan
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntityGetPinResponse'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPinByPanRequest'
  /issuers/{issuerId}/cards/pin:
    post:
      tags:
      - Card - Pin
      summary: Set a PIN for a card by PAN + PSN and/or expiry date
      operationId: setPinByPan
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntitySetPinResponse'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPinByPanRequest'
        required: true
  /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."
      parameters:
      - name: WL-Correlation-ID
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: Filtered Fields
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: issuerId
        in: path
        description: Issuer ID
        required: true
        schema:
          type: string
      - name: issuerCardExternalReference
        in: path
        description: issuerCardExternalReference
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorApiResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorApiResponse'
        '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'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseEntitySetPinResponse'
      security:
      - basic: []
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPinRequest'
        required: true
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
    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
    SetPinRequest:
      type: object
      required:
      - pinAttribute
      properties:
        event:
          type: string
          description: EXTERNAL (default), INTERNAL, ATM or IVR
        panExpiryDate:
          type: string
          description: Format MMYY
        pinAttribute:
          $ref: '#/components/schemas/PinAttribute'
      title: SetPinRequest
    PinAttribute:
      type: object
      required:
      - pinAlgorithmId
      - pinBlock
      - pinBlockFormat
      properties:
        encryptedSessionKey:
          $ref: '#/components/schemas/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
    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
    BadRequestErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadRequestResponseMetadata'
      title: BadRequestErrorApiResponse
    ApiResponseEntityGetPinResponse:
      type: object
      required:
      - responseMetadata
      properties:
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/GetPinResponse'
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
      title: ApiResponseEntityGetPinResponse
      description: Issuer response entity
    NotFoundErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/NotFoundResponseMetadata'
      title: NotFoundErrorApiResponse
    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
    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
    UnauthorizedErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/UnauthorizedResponseMetadata'
      title: UnauthorizedResponseMetadata
    SetPinByPanRequest:
      type: object
      required:
      - pinAttribute
      properties:
        event:
          type: string
          description: EXTERNAL (default -> just don't mention the field), INTERNAL, ATM or IVR
        pinAttribute:
          $ref: '#/components/schemas/PinAttribute'
        encryptedPan:
          $ref: '#/components/schemas/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: '#/components/schemas/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
    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
    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
    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
    SetPinResponse:
      type: object
      description: pinAttribute is just an echo of the input PIN
      properties:
        pinAttribute:
          $ref: '#/components/schemas/PinAttribute'
      title: SetPinResponse
    ApiResponseEntitySetPinResponse:
      type: object
      required:
      - responseMetadata
      properties:
        data:
          description: Response data
          allOf:
          - $ref: '#/components/schemas/SetPinResponse'
        responseMetadata:
          description: Response metadata
          allOf:
          - $ref: '#/components/schemas/ResponseMetadata'
      title: ApiResponseEntitySetPinResponse
      description: Issuer response entity
    InternalServerErrorErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/InternalServerErrorResponseMetadata'
      title: InternalServerErrorErrorApiResponse
    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
    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: '#/components/schemas/EncryptedData'
        encryptedPan:
          $ref: '#/components/schemas/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: '#/components/schemas/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
    GetPinResponse:
      type: object
      required:
      - externalPinAttribute
      properties:
        cardIdentifier:
          $ref: '#/components/schemas/CardIdentifier'
        externalPinAttribute:
          $ref: '#/components/schemas/PinAttribute'
      title: GetPinResponse
    BadGatewayErrorApiResponse:
      type: object
      required:
      - responseMetadata
      properties:
        responseMetadata:
          allOf:
          - $ref: '#/components/schemas/BadGatewayResponseMetadata'
      title: BadGatewayErrorApiResponse
    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
    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: '#/components/schemas/EncryptedData'
      title: GetPinRequest
    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
  securitySchemes:
    basic:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token