> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Change PIN
> Send a request to this endpoint to change PIN of a specific card version.
- Javascript generates an encrypted PIN block in ISO Format 1 from the cardholder-defined PIN. The PIN block is encrypted using a pre-shared double-length 3DES Zone PIN Key (ZPK). If zpkIndex is not specified, the first key is used by default.
- If sequenceNumber is not specified, the latest card version is used by default.
## OpenAPI
````yaml json-files/pin.openapi.json post /v1/pin/change
openapi: 3.0.3
info:
version: '1'
title: PIN API
servers:
- url: https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/issuer
description: UAT Sandbox
- url: https://api.{{tenant}}.eu.live.prod.mycore.enfuce.com/issuer
description: Production
security:
- bearerAuth: []
tags:
- name: PIN operations with pre-shared key
description: >
Endpoints for card PIN operations using pre-shared
key.
Note: When using these
endpoints, the client with access to the clear PIN must ensure proper PIN
handling in compliance with the card
scheme's security requirements.
- name: PIN operations using PKI
description: >
Endpoint for Card PIN operations using public key
cryptography.
Note:
If this endpoint is used, the client must make sure that the RSA key pair
is generated and used by the card-holder
device, giving no access to the private RSA key to any other system. This
way, no other system will have any means
to access the PIN code.
paths:
/v1/pin/change:
post:
tags:
- PIN operations with pre-shared key
summary: Change PIN
description: >
Send a request to this endpoint to change PIN of a specific card
version.
- Javascript generates an encrypted PIN block in ISO Format
1 from the cardholder-defined PIN. The PIN block is encrypted using a
pre-shared double-length 3DES Zone PIN Key (ZPK). If zpkIndex is not
specified, the first key is used by default.
- If sequenceNumber
is not specified, the latest card version is used by
default.
operationId: changePin
parameters:
- in: header
name: x-idempotency-key
required: false
schema:
type: string
description: Idempotency key for the request
- $ref: '#/components/parameters/x-audit-user'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChangePinRequestBody'
responses:
'200':
description: The encrypted PIN has been successfully changed.
content:
application/json: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
x-audit-user:
in: header
name: x-audit-user
required: false
description: Optional audit user header
schema:
type: string
schemas:
ChangePinRequestBody:
type: object
properties:
pinBlock:
type: string
description: >-
The encrypted PIN block is in ISO Format 1 and is represented in
hexadecimal.
example: 6E07465A3D19DDD1
cardId:
$ref: '#/components/schemas/Id'
sequenceNumber:
$ref: '#/components/schemas/SequenceNumber'
zpkIndex:
type: integer
description: >-
Pre-shared ZPK key index number. If it is not specified, the first
key is used by default.
example: 0
required:
- pinBlock
- cardId
title: ChangePinRequestBody
Id:
type: string
format: uuid
description: Unique identifier of a resource.
example: 20218aae-b15e-406c-9e9f-23735cd86a48
SequenceNumber:
type: integer
minimum: 1
description: >-
The sequence number of the card version, this value is also known as PSN
(pan sequence number)
example: 1
ErrorResponse:
type: object
properties:
type:
description: The problem type.
type: string
title:
description: The reason phrase of HttpStatus.
type: string
status:
description: HTTP problem status.
type: number
detail:
description: The problem detail.
type: string
instance:
description: The request path.
type: string
id:
description: Unique error identifier.
type: string
format: uuid
timestamp:
description: Date-time when error occurred.
type: string
format: date-time
responses:
BadRequest:
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: about:blank
title: Bad Request
status: 400
detail: 'JSON parse error: Unexpected character...'
instance: /v1/cards
id: 5cc541cb-f456-4331-b537-d2380fca0400
timestamp: '2026-02-24T12:34:56Z'
Unauthorized:
description: Unauthorized
Forbidden:
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: about:blank
title: Forbidden
status: 403
detail: Access Denied
instance: /v1/cards
id: 5cc541cb-f456-4331-b537-d2380fca0403
timestamp: '2026-02-24T12:34:56Z'
NotFound:
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: about:blank
title: Not Found
status: 404
detail: >-
Entity not found - Program with id:
2ec117b7-454e-4cc5-8b89-dea5485aab2b
instance: /v1/cards
id: 5cc541cb-f456-4331-b537-d2380fca0404
timestamp: '2026-02-24T12:34:56Z'
Conflict:
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: about:blank
title: Conflict
status: 409
detail: Customer number is not unique.
instance: /v1/cardholders
id: 5cc541cb-f456-4331-b537-d2380fca0409
timestamp: '2026-02-26T10:34:47.522+00:00'
InternalServerError:
description: Internal server error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: about:blank
title: Internal Server Error
status: 500
detail: Unexpected error occurred.
instance: /v1/cards
id: 5cc541cb-f456-4331-b537-d2380fca0500
timestamp: '2026-02-24T12:34:56Z'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````