Set PIN
Sets the PIN for a card. The PIN must be encrypted using the shared encryption algorithm before calling this API. The encrypted PIN should be generated by first creating a PIN block, then encrypting it. The expiryDate must match the card expiry date in MMYY format.
Authorization
tenantAuth The DCMS tenant name for multi-tenant isolation. Every API call must include this header to identify the client organization.
In: header
Header Parameters
The DCMS client or tenant name for multi-tenant isolation.
Request Body
application/json
Encrypted PIN value. Must be encrypted using the shared encryption algorithm before sending.
Kit number of the card for which PIN is being set.
Customer entity identifier who owns the card.
Card expiry date in MMYY format for validation.
Response Body
application/json
application/json
curl -X POST "https://api.dcms.example.com/v1/kit-manager/setPin" \ -H "tenant: ACME_BANK" \ -H "Content-Type: application/json" \ -d '{ "entityId": "validatePin0", "expiryDate": 729, "kitNo": "4240181647", "pin": "4faN/yNdT8E+5wVy/GlfTWYsVPHAYFPaPWDn+SSL59w=" }'{
"result": true,
"exception": null,
"pagination": null
}{
"result": null,
"exception": {
"errorCode": "PIN001",
"shortMessage": "Invalid PIN format",
"detailMessage": "The encrypted PIN format is invalid or decryption failed",
"httpStatus": "BAD_REQUEST",
"fieldError": [
"Invalid PIN encryption"
],
"languageCode": "en"
},
"pagination": null
}Regeneration of PIN Mailer POST
Regenerates a PIN mailer for an existing card. A PIN mailer is a physical document sent to the customer containing their card PIN. The addressType specifies which address (PERMANENT or COMMUNICATION) to use for delivery. The homeCurrencyCode is required for processing.
Set PIN V2 POST
Enhanced version of Set PIN that uses AES-GCM encryption for the PIN block. The PIN must be encrypted using a three-step process. Step 1 - PIN Block Generation using ISO 9564 Format 0 encoding where the PIN is XORed with the PAN (card number). Step 2 - AES-GCM Encryption where the PIN block from step 1 is encrypted using the shared set-PIN key with a random 16-byte IV and 128-bit authentication tag. Step 3 - The final encrypted PIN block is Base64 encoded containing the IV prepended to the ciphertext. The expiryDate must match the card expiry date in MMYY format.