​
Overview

Use defaultPIN when an endpoint asks you to send a PIN during account setup or a PIN change flow. You must never send the PIN in plaintext. Instead, you encode the PIN into a PIN block, encrypt that PIN block with the Cardcore RSA public key, and submit the encrypted result with the matching key fingerprint.

​
Object shape

{
  "defaultPIN": {
    "encryptedData": "7F8D92H3...",
    "publicKeyFingerprint": "A884D774..."
  }
}
​
defaultPIN.encryptedData
string
required
The RSA-encrypted PIN block.Send this as a 512-character uppercase hex string.This value comes from encrypting a 16-byte PIN block with an RSA 2048-bit public key by using PKCS#1 v1.5 padding.This field is non-deterministic.The same PIN will produce a different ciphertext each time because PKCS#1 v1.5 uses random padding.
​
defaultPIN.publicKeyFingerprint
string
required
The fingerprint of the DER-encoded RSA public key used for encryption.The server uses this value to identify the correct private key for decryption.Fetch this fingerprint from the encryption key endpoint before you submit the request.

​
Why the PIN is encrypted this way

The PIN is treated as sensitive cardholder data. Cardcore does not accept plaintext PIN values in API requests. The PIN is first converted into a fixed-length PIN block so the server can decode it consistently after decryption. That PIN block is then encrypted with RSA PKCS#1 v1.5 by using the public key published for your environment. This design gives you these protections:
  • The raw PIN never travels over the API as readable text.
  • Only the server that holds the matching private key can decrypt the payload.
  • Random padding prevents the same PIN from producing the same ciphertext on every request.
  • The fingerprint lets the server choose the exact private key that matches the public key you used.

​
Client integration flow

Follow these steps in your client before you send defaultPIN.

​
1. Fetch the encryption key

Call the encryption key endpoint and store:
  • the RSA public key
  • the public key fingerprint
Use the encryption key endpoint for your environment. If you are integrating with Cardcore, use Get RSA key.

​
2. Validate the PIN

Before you encrypt, confirm that the PIN:
  • contains only numeric digits
  • has a length from 4 to 12
Reject invalid input on the client before you attempt encryption.

​
3. Build the PIN block

Create the PIN block with this format: 
"1" + hex(PIN length) + PIN digits + "F" padding to 16 characters total
Examples:
PINPIN block
1234141234FFFFFFFFFF
12345616123456FFFFFFFF
1234567890121C123456789012FF

​
4. Encrypt the PIN block

Convert the PIN block string to raw bytes. Encrypt those bytes with the RSA public key by using:
  • RSA
  • PKCS#1 v1.5 padding
  • a 2048-bit key

​
5. Hex-encode the ciphertext

Take the encrypted bytes and hex-encode them in uppercase. That uppercase hex string becomes defaultPIN.encryptedData. For a 2048-bit RSA key, the encrypted output is always 256 bytes, which becomes 512 uppercase hex characters.

​
6. Attach the fingerprint

Copy the fingerprint from the key-fetch response into defaultPIN.publicKeyFingerprint. Do not derive a different value locally unless your Cardcore integration explicitly tells you to.

​
Example request fragment

{
  "defaultPIN": {
    "encryptedData": "7F8D92H3A1B4C6D8E0F1A2B3C4D5E6F7...",
    "publicKeyFingerprint": "A884D7749D0E31C1B4E65F8A7B2C1190"
  }
}

​
Testing note

Do not compare encryptedData by exact value in tests. RSA PKCS#1 v1.5 encryption is non-deterministic, so the ciphertext changes across runs even when the input PIN is the same. Instead, validate:
  • that the value is uppercase hex
  • that the value length is exactly 512
  • that the fingerprint matches the key you fetched
  • that the server accepts the encrypted payload