Set PIN

PUT

/integration/cards/{id}/pin

Early access - contact your account manager to enable cards for your organization.

Sets a new PIN for a card. The PIN is used for ATM withdrawals and chip-and-PIN payments. Start with POST /integration/cards/{id}/encrypted-envelope; then, on the cardholder's device, format the new 4-digit PIN as an ISO 9564 format 2 PIN block and encrypt it with the session key using AES-GCM.

The new PIN is active immediately. The response has an empty body.

Errors: 400 Bad Request if the PIN block cannot be decrypted, the PIN is not 4 digits, or the envelope has expired; 404 Not Found if the card does not exist; 422 Unprocessable Content if the card is not active or frozen.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Path Params

Body Params application/json

Example

{
    "protocol": "string",
    "encryptedSessionKey": "string",
    "encryptedPinBlock": {
        "iv": "q3Jd2fX0bP1k9sLw",
        "data": "N2Y4ZTFhYzQ5ZDJiM2M1ZTZmN2E4YjljMGQxZTJmM2E="
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request PUT 'https://my.test-1.account.finlego.com/api/merchant/integration/cards//pin' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "protocol": "string",
    "encryptedSessionKey": "string",
    "encryptedPinBlock": {
        "iv": "q3Jd2fX0bP1k9sLw",
        "data": "N2Y4ZTFhYzQ5ZDJiM2M1ZTZmN2E4YjljMGQxZTJmM2E="
    }
}'

Responses

🟢200OK

This response does not have a body.

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠422Parameter Error

🔴500Server Error

Modified at 2026-09-29 11:11:16

Reveal card details

List card transactions