> ## Documentation Index > Fetch the complete documentation index at: https://docs.enfuce.com/llms.txt > Use this file to discover all available pages before exploring further. # Request PIN Control access token by plasticId. > This operation is used to create the PIN control access token. The successful response from this call returns an _id_, a _pinURL_ for mobile device webview and _pinFrameURL_ for an iframe in desktop browser flow. _Id_ is valid for 30 seconds. For mobile webview, device should be instructed to do a POST call to the _pinURL_ with the content of the _id_ in a form field named _controlId_. For desktop browser flow, iframe should be opened to _pinFrameURL_ with query parameter _key_, which needs to be agreed with Enfuce beforehand. After iframe has been loaded, browser should make a _window.postMessage()_ call to the iframe. The message object should contain fields _operation_ (with value _view-pin_ or _set-pin_) and _controlId_. ## OpenAPI ````yaml pincontrol post /v2/plastic/{plasticId} openapi: 3.0.3 info: description: > Endpoint for managing an access token used to view or set PIN. This is a PCI DSS Category 2 service. # Introduction This service enables the cardholders to access their PIN using their device, through an App, or through a web interface. The user is able to do two different things with this access token: - View PIN - Set PIN (this is usable at card application time, before the card has been produced) ![Example user experience ](https://enfuce-public-resources.s3.eu-central-1.amazonaws.com/public/pincontrol-visualization.png) ## Flow There are two main stages of the flow. 1. Requesting a PIN Control access token (this is done using this web service). 2. Instructing the cardholder's mobile device webview or desktop browser to access a certain URL to view or set PIN. The service is designed to avoid exposure of sensitive data, therefore the PIN is sent directly from the service endpoint to the card holder device. ## Default CSS for View PIN When using web interface to access PIN it is possible to style the corresponding HTML page. The default styling is shown below. Note that it is possible to customize this. ![ Example user experience ](https://enfuce-public-resources.s3.eu-central-1.amazonaws.com/public/pincontrol-view-pin-default-css.png) ## View/Set PIN page callbacks for mobile devices View/Set PIN pages provide following callbacks for interacting with the native application. For Android the javascript interface name is _android_handler_. Listed below are all the callbacks that can be implemented. Example call: window.android_handler.pin_valid(true) For iOS, the message handler name is _ios_handler_. And the posted message body will contain _event_-field containing the callback name and possibly _pin_valid_-field. Example call: window.webkit.messageHandlers.ios_handler.postMessage({ event: 'pin_valid', pin_valid: true }); **view_pin_success()** called when PIN is successfully shown. **view_pin_error()** called when there was an error viewing PIN. **set_pin_success()** called when PIN is successfully set. **set_pin_error()** called when there was an error setting up the web page or setting of the PIN failed. The flow should be restarted. **set_pin_validation_error()** called when set PIN was tried, but PIN was invalid. **pin_valid(valid)** called everytime when input field is updated. Boolean parameter _valid_ is true if PIN is valid. **set_pin()** can be called by native app to initiate set PIN. ## View/Set PIN page callbacks in desktop browser flow The iframe will _window.postMessage()_ events back to the parent page. Events are the same as in mobile device flow and the format is the same as for iOS as described above. Example call: iframe.contentWindow.postMessage({operation: 'set-pin-set'}, targetOrigin); version: '1' title: Card PIN Control API contact: name: Enfuce Financial Services url: https://enfuce.com email: info@enfuce.com x-logo: url: https://developer.enfuce.com/images/enfuce.svg altText: Enfuce logo servers: - url: >- https://integration-api-cat2.{{environment}}.ext.{{realm}}.cia.enfuce.com/pincontrol - url: https://integration-api-cat2.live.ext.prod.cia.enfuce.com/pincontrol description: Live environment security: [] tags: - name: PIN Control handling description: Endpoint for accessing PIN Control tokens paths: /v2/plastic/{plasticId}: post: tags: - PIN Control handling summary: Request PIN Control access token by plasticId. description: > This operation is used to create the PIN control access token. The successful response from this call returns an _id_, a _pinURL_ for mobile device webview and _pinFrameURL_ for an iframe in desktop browser flow. _Id_ is valid for 30 seconds. For mobile webview, device should be instructed to do a POST call to the _pinURL_ with the content of the _id_ in a form field named _controlId_. For desktop browser flow, iframe should be opened to _pinFrameURL_ with query parameter _key_, which needs to be agreed with Enfuce beforehand. After iframe has been loaded, browser should make a _window.postMessage()_ call to the iframe. The message object should contain fields _operation_ (with value _view-pin_ or _set-pin_) and _controlId_. operationId: createPinControlTokenByPlasticIdV2UsingPOST parameters: - name: plasticId in: path description: The id of the plastic for which the PIN should be accessed required: true schema: type: string format: biginteger - name: auditUser in: query description: The audit user to log the request required: true schema: type: string requestBody: $ref: '#/components/requestBodies/createPinControlResourceBody' responses: '201': description: Successful creation of the access token content: application/json: schema: $ref: '#/components/schemas/PinControlResponseBody' '401': $ref: '#/components/responses/error401' '403': $ref: '#/components/responses/error403' '404': description: Card not Found content: application/json: schema: $ref: '#/components/schemas/errorResponse' '500': $ref: '#/components/responses/error500' components: requestBodies: createPinControlResourceBody: content: application/json: schema: $ref: '#/components/schemas/PinControlResourceBody' description: The related PIN control request data required: true schemas: PinControlResponseBody: type: object properties: id: type: string description: The ID of this PIN Control access token. pinURL: type: string description: >- The URL that the cardholder's mobile device webview should browse to for accessing the PIN. pinFrameURL: type: string description: >- The URL of the iframe for desktop browser based flows for accessing PIN. required: - id title: pinControlResponseBody errorResponse: type: object properties: code: type: string description: An error code indicating what kind of error. I.e. HTTP error code message: type: string description: Error message in human-readable format id: type: string format: uuid description: Unique error identifier errorCode: type: string description: Enfuce code for a specific error type errorType: type: string description: Error type enum: - STATIC_VALIDATION_ERROR - DYNAMIC_VALIDATION_ERROR - INTEGRATION_ERROR - SECURITY_ERROR - UNEXPECTED_ERROR errorReason: type: string description: Free-form text explaining the error reason timestamp: type: string format: date-time description: Datetime when error occurred PinControlResourceBody: type: object properties: scope: type: string description: Describes the scope of the operation that is authorized by the user. enum: - VIEW_PIN - SET_PIN required: - scope title: pinControlResourceBody responses: error401: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/errorResponse' error403: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errorResponse' error500: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/errorResponse' ````