# Set a PIN for a Full PAN Issuer source: https://developer.mastercard.com/mastercard-processing-core/documentation/use-cases/pin-management/set-pin-full-pan-issuer/index.md ## Overview {#overview} These use cases describe the process in which a cardholder sets a PIN for the card, and the PAN is known to your system. To ensure an appropriate level of security when transmitting sensitive data (such as the PIN), the `newPinBlock` field must be encrypted in the communication between your system and the Mastercard Processing CMS, in addition to the JWE payload encryption. The PIN Block, in ISO 0 format, can be encrypted either symmetrically using a ZPK exchanged during the onboarding process or asymmetrically by calling the `getPublicRsaKey` operation to fetch the public RSA key. It is up to you to decide which encryption method to use. ## Set a PIN for a full PAN issuer (symmetric PIN block encryption) {#set-a-pin-for-a-full-pan-issuer-symmetric-pin-block-encryption} This use case describes the process in which a cardholder sets a PIN for the card, and the PAN is not known to your system and the PIN Block in ISO 0 format is encrypted symmetrically using ZPK exchanged during the onboarding process. ### Sequence diagram {#sequence-diagram} Diagram set-pin-full-pan-issuer-sym ### Explanation {#explanation} 1. The cardholder sets the PIN for the card using the mobile application or e-banking service. 2. The mobile application or e-banking service sends a `PUT` request to the `/cards/{card_contract_id}/pins` endpoint, passing the `cardExpiryDate`, `cardSequenceNumber`, and `newPinBlock` fields in ISO format 0 using symmetrical encryption using the Zone PIN Key (ZPK). Tip: Since multiple `CardPlastic` objects can be assigned to a single `CardContract`, you need to include the `cardExpiryDate` and `cardSequenceNumber` in the request to clearly identify the specific `CardPlastic` for which you want to set the PIN. The `cardSequenceNumber` can be obtained by utilizing the `getCardPlastics` operation. If `cardSequenceNumber` will not be provided the newest `CardPlastic` will be updated. 3. The API retrieves the PAN number from the CMS based on the `card_contract_id` value provided in the request. 4. Mastercard Processing decrypts the `newPinBlock` using ZPK. 5. The API sends decrypted `newPinBlock` to the CMS, which then decodes it and stores the new PIN. After setting a new PIN, the CMS generates an EMV script to synchronize the offline PIN on the chip of the CardPlastic during the earliest authorization process. Note: If the PIN is changed on a physical `CardPlastic` that is in the `Locked` status (it has not been activated yet), it activates the `CardPlastic` specifically for e-commerce and token-based transactions. 6. The API returns HTTP `204`, confirming that the PIN is successfully set. 7. The mobile application or e-banking service notifies the cardholder that the PIN is successfully set. Warning: The `setPin` only updates the PIN in the CMS and not on the chip of the physical card. To synchronize the PIN on the chip, a contact online transaction is required. Tip: Refer to [PIN Block Formation and Encryption Process](https://developer.mastercard.com/mastercard-processing-core/tutorial/pin-encryption-process/index.md) tutorial for more information with code samples to help you with the integration. Refer to [Sandbox testing](https://developer.mastercard.com/mastercard-processing-core/documentation/sandbox-testing/pin-management/set-pin-for-full-pan-issuer/index.md) for information on how to execute the use case in the Sandbox environment. ### Endpoint {#endpoint} API Reference: `PUT /cards/{card_contract_id}/pin` ## Set a PIN for a full PAN issuer (asymmetric PIN block encryption) {#set-a-pin-for-a-full-pan-issuer-asymmetric-pin-block-encryption} This use case describes the process in which a cardholder sets a PIN for the card, and the PAN is not known to your system and the PIN block in ISO 0 format is encrypted asymmetrically using Public RSA key. ### Sequence diagram {#sequence-diagram-1} Diagram set-pin-full-pan-issuer-asym ### Explanation {#explanation-1} 1. The cardholder sets the PIN for the card using the mobile application or e-banking service. 2. The mobile application or e-banking service sends a `GET` request to the `/public-keys?data_type_to_secure=PIN_BLOCK` endpoint. 3. The API responds with the `keyIndex` and `publicRsaKey`. 4. The mobile application or e-banking service generates a PIN block using ISO format 0 encrypted with the `publicRsaKey` received in step 3. Tip: A Public RSA key can be in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) or [DER](https://en.wikipedia.org/wiki/X.690#DER_encoding) format depending on the onboarding configuration. By default, the DER format is used. 5. The mobile application or e-banking service sends a `PUT` request to the `/cards/{card_contract_id}/pin` endpoint passing: * `keyIndex` of the `publicRsaKey` used in step 4 in the header * encrypted `newPinBlock`, `cardExpiryDate`, and `cardSequenceNumber` in the request body Tip: Since multiple `CardPlastic` objects can be assigned to a single `CardContract`, you need to include the `cardExpiryDate` and `cardSequenceNumber` in the request to clearly identify the specific `CardPlastic` for which you want to set the PIN. The `cardSequenceNumber` can be obtained by utilizing the `getCardPlastics` operation. If `cardSequenceNumber` will not be provided the newest `CardPlastic` will be updated. 6. The API retrieves the PAN number from the CMS based on the `card_contract_id` value provided in step 5. 7. The API decrypts the `newPinBlock` by using a Private RSA key. 8. The API sends decrypted `newPinBlock` to the CMS, which then decodes it and stores the new PIN. After setting new PIN, the CMS generates an EMV script to synchronize the offline PIN on the chip of the `CardPlastic` during the earliest authorization process. Note: If the PIN is changed on a physical `CardPlastic` that is in the `Locked` status (it has not been activated yet), it activates the `CardPlastic` specifically for e-commerce and token-based transactions. 9. The API returns the HTTP status `204`. 10. The mobile application or e-banking service notifies the cardholder that the PIN is successfully set. Warning: The `setPin` only updates the PIN in the CMS and not on the chip of the physical card. To synchronize the PIN on the chip, a contact online transaction is required. Tip: Refer to [PIN Block Formation and Encryption Process](https://developer.mastercard.com/mastercard-processing-core/tutorial/pin-encryption-process/index.md) tutorial for more information with code samples to help you with the integration. Refer to [Sandbox testing](https://developer.mastercard.com/mastercard-processing-core/documentation/sandbox-testing/pin-management/set-pin-for-full-pan-issuer/index.md) for information on how to execute the use case in the Sandbox environment. ### Endpoint {#endpoint-1} API Reference: `GET /public-keys` API Reference: `PUT /cards/{card_contract_id}/pin`