OpenAPI Specification
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