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 - CardPinState API
contact: {}
host: sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/card-issuing
basePath: /api/v2
schemes:
- https
tags:
- name: Card - CardPinState
description: Card Pin State
paths:
/issuers/{issuerId}/cards/pin-state:
post:
tags:
- Card - CardPinState
summary: Card Pin State With EnquireCardStates
operationId: getCardPinStateByCard
description: "Operation which provides the currently effective details of the card entities matching the passed search criteria. \nSupported criteria are: Card reference or Card number or Alternative card number"
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
description: WL-Correlation-ID
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: WL-Peer-ID
in: header
required: false
type: string
- in: body
name: body
description: body
required: true
schema:
$ref: '#/definitions/RetrieveCardPinStateRequest'
- name: issuerId
in: path
description: issuerId
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCardPinState'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedResponseMetadata'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
security:
- basic: []
deprecated: false
/issuers/{issuerId}/cards/pin-state/{accountReference}:
get:
tags:
- Card - CardPinState
summary: Card Pin State With EnquireCardStates
operationId: getCardPinStateByAcctNbr
produces:
- application/json
parameters:
- name: WL-Correlation-ID
in: header
description: WL-Correlation-ID
required: false
type: string
- name: WL-Username
in: header
required: false
type: string
- name: WL-Peer-ID
in: header
required: false
type: string
- name: accountReference
in: path
description: accountReference
required: true
type: string
- name: issuerId
in: path
description: issuerId
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/ApiResponseEntityCardPinStateList'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestErrorApiResponse'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/UnauthorizedResponseMetadata'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ForbiddenErrorApiResponse'
'404':
description: Not found
schema:
$ref: '#/definitions/NotFoundErrorApiResponse'
'500':
description: Internal server error
schema:
$ref: '#/definitions/InternalServerErrorErrorApiResponse'
'502':
description: Bad gateway
schema:
$ref: '#/definitions/BadGatewayErrorApiResponse'
security:
- basic: []
deprecated: false
definitions:
ApiResponseEntityCardPinState:
type: object
required:
- responseMetadata
properties:
data:
description: Response data
allOf:
- $ref: '#/definitions/CardStateResponse'
responseMetadata:
description: Response metadata
allOf:
- $ref: '#/definitions/ResponseMetadata'
title: ApiResponseEntityCardPinState
description: Issuer response entity
ApiResponseEntityCardPinStateList:
type: object
required:
- responseMetadata
properties:
data:
type: array
description: Response data
items:
$ref: '#/definitions/CardStateResponse'
responseMetadata:
$ref: '#/definitions/ResponseMetadata'
title: ApiResponseEntityCardPinStateList
description: Issuer response entity
Links:
type: object
required:
- self
properties:
self:
type: string
example: /x/{x}?x=x
description: Service method URL
next:
type: string
example: /x/{x}?page[offset]=2
description: URL pagination query parameter next page
title: Links
NotFoundResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 404
description: HTTP status code
statusMessage:
type: string
example: Not found
description: Executed REST API status message
title: NotFoundResponseMetadata
BadRequestResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 400
description: HTTP status code
statusMessage:
type: string
example: Bad request
description: Executed REST API status message
title: BadRequestResponseMetadata
ResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
links:
description: Metadata Links
allOf:
- $ref: '#/definitions/Links'
statusMessage:
type: string
example: Executed successfully
description: Executed REST API status message
statusCode:
type: integer
format: int32
example: 200
description: HTTP status code
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
timeTakenMs:
type: integer
format: int64
example: 12
description: Wall clock time required from service to generate the response
title: ResponseMetadata
BadGatewayResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 502
description: HTTP status code
statusMessage:
type: string
example: Bad Gateway
description: Executed REST API status message
title: BadGatewayResponseMetadata
CardStateResponse:
type: object
properties:
accountReference:
type: string
description: 'DynamicReference
minLength: 1
maxLength: 100'
alternativePan:
type: string
description: 'AlternativeCardNumber
minLength: 1
maxLength: 100'
pan:
type: string
description: 'CardNumber
minLength: 1
maxLength: 28'
cardReference:
type: string
description: 'DynamicReference
minLength: 1
maxLength: 100'
maximumPinTryCounter:
type: string
description: "minimum: 0\nmaximum: 9999\nThe maximum amount of failed PIN tries which the cardholder can do. \nAfter that every PIN based transaction is declined until the PIN try counter is reset. \nNo matter whether the PIN is correct or not."
nfcStatus:
type: string
description: "Indicates the status of the NFC antenna. \nPossible values are:\n- None (NFC antenna is not present)\n- Enabled (NFC antenna is enabled)\n- EnablingInProgress (Enabling of NFC antenna has been initiated but is not yet finished)\n- Disabled (NFC antenna is disabled)\n- DisablingInProgress (Disabling of NFC antenna has been initiated but is not yet finished)\n- Locked (NFC antenna is disabled for transport but will be automatically enabled by the card once the card is used)"
nfcStatusChangeCounter:
type: string
description: 'minimum: 0
maximum: 9999
Number of changes performed on NfcStatus. Present in case NfcStatus is present.'
nfcStatusChangeTime:
type: string
description: 'Example: 20200518235959
Time of the last NfcStatus modification. Present in case NfcStatus is present.'
offlinePinChangeStatus:
type: string
description: "Examples: List [ \"Pending\", \"InProgress\", \"Successful\", \"Failed\" ]\nIndicates the current status of adapting the offline PIN. \nPossible values are:\nPending (offline PIN needs to be changed but no script has been sent so far)\nInProgress (at least one PIN change script has been sent; receipt of a positive or negative confirmation is outstanding)\nSuccessful (offline PIN change finished successfully)\nFailed (offline PIN change did not finish successfully)"
offlinePinChangeStatusChangeTime:
type: string
format: date-time
description: 'Timestamp when the pinCheckParameterStatus was changed.
Example: 2012-12-31T22:00:00.000'
offlinePinChangeTryCounter:
type: string
description: "minimum: 0\nmaximum: 9999\nNumber of attempts to adapt the offline PIN, i.e. number of times a PIN change script has been sent in a response message. \nPresent in case OfflinePinChangeStatus is present."
pinCheckParameter1:
type: string
description: 'minLength: 1
maxLength: 64
Depending on the used PIN verification method this field has different format and meaning:
- IBM 3642 algorithm: PIN offset, decimal digits
- German DK (Deutsche Kreditwirtschaft),: PRW (PIN-Referenzwert), 64 hexadecimal digits
- German Proprietary: PRW (PIN-Referenzwert), 32 hexadecimal digits
VISA: PVV, 4 decimal digits'
pinCheckParameter2:
type: string
description: 'minLength: 1
maxLength: 64
Depending on the used PIN verification method this field has different format and meaning:
- German DK (Deutsche Kreditwirtschaft): Random value, 8 hexadecimal digits
- German Proprietary: PCC (PIN Change Counter), 4 decimal digits'
pinCheckParameterStatus:
type: string
description: "Examples: List [ \"Active\", \"Blocked\" ]\nStatus of PIN check parameters. \nPossible values are:\nActive\nBlocked"
pinCheckParameterStatusChangeTime:
type: string
format: date-time
description: 'Timestamp when the OfflinePinChangeStatus was changed.
Example: 2012-12-31T22:00:00.000'
pinTryCounter:
type: string
description: 'minimum: 0
maximum: 9999
Number of failed PIN entries.'
pinTryCounterChangeTime:
type: string
format: date-time
description: 'Timestamp pattern: ^[0-9]{4}([0][1-9]|[1][012])(0[0-9]|[12][0-9]|3[01])(2[0-3]|[01][0-9])([0-5][0-9])([0-5][0-9])$|^$
Example: 20200518235959'
pinTryCounterResetTime:
type: string
format: date-time
description: 'Timestamp pattern: ^[0-9]{4}([0][1-9]|[1][012])(0[0-9]|[12][0-9]|3[01])(2[0-3]|[01][0-9])([0-5][0-9])([0-5][0-9])$|^$
Example: 20200518235959'
pinTryCounterResetType:
type: string
description: 'Examples: List [ "Daily", "Fixed", "Never", "Other" ]
Indicates the algorithm to reset the PIN try counter after exceeding the maximum number of allowed wrong entries.
- Daily (Every day at a certain time)
- Fixed (After expiry of a time interval)
- Never (No automatic reset)'
expiryDate:
type: string
description: 'The expiry date of the card
Format is MMYY'
status:
type: string
description: The status of the card
blockingReason:
type: string
description: The reason why the card was blocked (if the card status is blocked)
title: CardStates
NotFoundErrorApiResponse:
type: object
required:
- responseMetadata
properties:
responseMetadata:
allOf:
- $ref: '#/definitions/NotFoundResponseMetadata'
title: NotFoundErrorApiResponse
BadGatewayErrorApiResponse:
type: object
required:
- responseMetadata
properties:
responseMetadata:
allOf:
- $ref: '#/definitions/BadGatewayResponseMetadata'
title: BadGatewayErrorApiResponse
InternalServerErrorErrorApiResponse:
type: object
required:
- responseMetadata
properties:
responseMetadata:
allOf:
- $ref: '#/definitions/InternalServerErrorResponseMetadata'
title: InternalServerErrorErrorApiResponse
InternalServerErrorResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 500
description: HTTP status code
statusMessage:
type: string
example: Internal server error
description: Executed REST API status message
title: InternalServerErrorResponseMetadata
ForbiddenErrorApiResponse:
type: object
required:
- responseMetadata
properties:
responseMetadata:
allOf:
- $ref: '#/definitions/ForbiddenResponseMetadata'
title: ForbiddenErrorApiResponse
RetrieveCardPinStateRequest:
description: One of cardNumber, alternativeCardNumber or cardReference is mandatory
type: object
properties:
pan:
type: string
description: "minLength: 1\nmaxLength: 28\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
alternativePan:
type: string
description: "minLength: 1\nmaxLength: 100\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
cardReference:
type: string
description: "minLength: 1\nmaxLength: 100\nIdentifies the cards those details have to be provided. \nEither CardReference, CardNumber, AlternativeCardNumber must be provided."
title: RetrieveCardPinStateRequest
BadRequestErrorApiResponse:
type: object
required:
- responseMetadata
properties:
responseMetadata:
allOf:
- $ref: '#/definitions/BadRequestResponseMetadata'
title: BadRequestErrorApiResponse
UnauthorizedResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 401
description: HTTP status code
statusMessage:
type: string
example: Unauthorized
description: Executed REST API status message
title: UnauthorizedResponseMetadata
ForbiddenResponseMetadata:
type: object
required:
- correlationId
- responseDateTime
- statusCode
- statusMessage
properties:
correlationId:
type: string
description: Correlation Identifier
responseDateTime:
type: string
example: format:yyyy-MM-dd'T'HH:mm:ss.SSSZ
description: Timestamp when response date was generated
statusCode:
type: integer
format: int32
example: 403
description: HTTP status code
statusMessage:
type: string
example: Forbidden
description: Executed REST API status message
title: ForbiddenResponseMetadata
securityDefinitions:
basic:
type: oauth2
flow: application
tokenUrl: https://sbx-wlip.api1-eu2.psapigateway.preprod.giservices.io/token