Update card PIN

PUT

/v1/cards/{cardId}/pin

Updates the card PIN.

PIN Block Format (ISO 9564-1 Format 2): The PIN must be formatted as a 16-character PIN block before encryption:

• Byte 0: Control field (2 indicates Format 2)
• Byte 1: PIN length in hexadecimal (4-12)
• Bytes 2-(1+N): The actual PIN digits
• Remaining bytes: Padding (F)

Example: A 4-digit PIN “5678” would be encoded as: 245678FFFFFFFFFF

Formatting the PIN block:

const pinBlock = `2${pinLength.toString(16)}${pin}${'F'.repeat(14 - pinLength)}`;

Encryption:

1. Generate a random AES-128 key
2. Encrypt the PIN block using AES-128-GCM with the random key
3. RSA-encrypt the AES key using the server’s public key
4. Send the RSA-encrypted key as encryptedKey and the AES-encrypted PIN block as encryptedPin

Validation:

• PIN must be 4-12 digits
• Weak PINs (repeating like 1111, sequential like 1234) are rejected

Authorizations

• bearerAuth

Parameters

Path Parameters

cardId

required

The id of the card whose pin is being updated

string

>= 1 characters

Request Body ^required

object

encryptedKey

required

Base64-encoded RSA-encrypted AES-128 key used for PIN encryption

string

>= 1 characters

encryptedPin

required

AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block.

object

iv

required

Base64-encoded initialization vector for AES-GCM decryption

string

>= 1 characters

data

required

Base64-encoded AES-GCM encrypted PIN block

string

>= 1 characters

object

encryptedKey

required

Base64-encoded RSA-encrypted AES-128 key used for PIN encryption

string

>= 1 characters

encryptedPin

required

AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block.

object

iv

required

Base64-encoded initialization vector for AES-GCM decryption

string

>= 1 characters

data

required

Base64-encoded AES-GCM encrypted PIN block

string

>= 1 characters

object

encryptedKey

required

Base64-encoded RSA-encrypted AES-128 key used for PIN encryption

string

>= 1 characters

encryptedPin

required

AES-128-GCM encrypted PIN block. The plaintext must be an ISO 9564-1 Format 2 PIN block.

object

iv

required

Base64-encoded initialization vector for AES-GCM decryption

string

>= 1 characters

data

required

Base64-encoded AES-GCM encrypted PIN block

string

>= 1 characters

Responses

200

Response for status 200

object

success

required

boolean

401

Response for status 401

object

type

A URI reference that identifies the problem type

string

default: about:blank

title

required

A short, human-readable summary of the problem type

string

status

required

The HTTP status code

number

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

realm

The authentication realm

string

scope

The required scope for this resource

string

404

Response for status 404

object

type

A URI reference that identifies the problem type

string

default: about:blank

title

required

A short, human-readable summary of the problem type

string

status

required

The HTTP status code

number

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

resourceType

required

The type of resource that was not found

string

resourceId

required

The identifier of the resource that was not found

string

500

Response for status 500

object

type

A URI reference that identifies the problem type

string

default: about:blank

title

required

A short, human-readable summary of the problem type

string

status

required

The HTTP status code

number

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string