PIN and card security
Set and change a PIN, manage the try counter, and generate or verify the card verification values.
setCardPin
Sets the PIN for a specified card. It checks card status before updating the PIN, ensuring no issues with the customer’s card status before processing the request.
Part of:
-
Journey 01 · Launching a new card product — step 5, Activate and set the PIN
-
Journey 01 · Launching a new card product — step 4, Activate, PIN, transact
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
setCardPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe platform's own handle for a card, and the identifier most operations take. It is returned by every operation that creates a card and by the card listings; a caller does not compose one.
clearPinExactly four digits today, and the four is not in this contract: setCardPin hardcodes it while verifyCardPin and changeCardPin read it from the platform's Pin parameter, so a tenant that changes that parameter changes two of the three.
setCardPin › Responses
Success
successWhether the operation did what it was asked to. A false here arrives with HTTP 200, so it has to be read rather than inferred from the status.
encryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
changeCardPin
Changes the PIN of a credit card. Validates the card status to ensure it is neither under configuration nor with payment issues. Uses current PIN and new PIN, calls the Card PIN service, and returns the encrypted PIN, change status, success flag, and verification result.
Part of:
- Journey 02 · Managing a card product — step 3, PIN and verification
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
changeCardPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe platform's own handle for a card, and the identifier most operations take. It is returned by every operation that creates a card and by the card listings; a caller does not compose one.
currentCardPinChecked against the platform's Pin parameter rather than a fixed length, so it follows the tenant's configuration and can change without a release.
newCardPinChecked against the platform's Pin parameter rather than a fixed length, so it follows the tenant's configuration and can change without a release.
changeCardPin › Responses
Success
successWhether the operation did what it was asked to. A false here arrives with HTTP 200, so it has to be read rather than inferred from the status.
verifiedWhether the value presented matched the one held.
changedencryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
verifyCardPin
Verifies the entered PIN against the stored one for the provided card, checking for validity and exceeding attempt counts.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyCardPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe platform's own handle for a card, and the identifier most operations take. It is returned by every operation that creates a card and by the card listings; a caller does not compose one.
clearCardNumberA card number is not stored by these services; the platform keeps a shadow card number instead.
clearPinExactly four digits today, and the four is not in this contract: setCardPin hardcodes it while verifyCardPin and changeCardPin read it from the platform's Pin parameter, so a tenant that changes that parameter changes two of the three.
verifyCardPin › Responses
Success
verifiedWhether the value presented matched the one held.
lastTryCountHow many failed attempts stand against the card.
tryCountExceedWhether the card has run out of attempts. The card is blocked when it has.
verifyRsaPin
Verifies the RSA pin for a given card, including the option to use a static salt for enhanced security.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyRsaPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card the operation acts on, by its shadow card number — the platform's own reference, not the PAN.
ePBThe encrypted PIN block to verify.
Its size follows the block format and the key it was built with rather than a column, so no length is published.
operationDateThe date the PIN block was produced under. The block and this date are verified as a pair.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
verifyRsaPin › Responses
Success
verifiedWhether the value presented matched the one held.
lastTryCountHow many failed attempts stand against the card.
tryCountExceedWhether the card has run out of attempts. The card is blocked when it has.
responseCodeThe downstream system's own result code, passed through. 00 and 0 are success; anything else is its refusal, and responseReasonCode or the description says which.
responseDescriptionThe description of responseCode, carried alongside it for display. It is not a key: match on the code.
verifyRsaPinWithStaticSalt
Verifies the RSA pin for a given card, including the option to use a static salt for enhanced security.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyRsaPinWithStaticSalt › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card the operation acts on, by its shadow card number — the platform's own reference, not the PAN.
ePBThe encrypted PIN block to verify.
Its size follows the block format and the key it was built with rather than a column, so no length is published.
operationDateThe date the PIN block was produced under.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
staticSaltThe salt the PIN block was built with. This is the only field that separates this operation from verifyRsaPin; the checks are otherwise identical.
A cryptographic input rather than stored data: no column behind it and no length published.
verifyRsaPinWithStaticSalt › Responses
Success
verifiedWhether the value presented matched the one held.
lastTryCountHow many failed attempts stand against the card.
tryCountExceedWhether the card has run out of attempts. The card is blocked when it has.
responseCodeThe downstream system's own result code, passed through. 00 and 0 are success; anything else is its refusal, and responseReasonCode or the description says which.
responseDescriptionThe description of responseCode, carried alongside it for display. It is not a key: match on the code.
setRsaPin
Sets a new RSA Pin for the card. It validates the card status and performs the RSA Pin update operation for a customer, providing encrypted pin and relevant response information.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
setRsaPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card whose PIN is set.
ePBThe encrypted PIN block.
Its size follows the block format and the key it was built with rather than a column, so no length is published.
operationDateThe date the operation is stamped with.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
setRsaPin › Responses
Success
successWhether the operation did what it was asked to. A false here arrives with HTTP 200, so it has to be read rather than inferred from the status.
encryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
responseCodeThe downstream system's own result code, passed through. 00 and 0 are success; anything else is its refusal, and responseReasonCode or the description says which.
responseDescriptionThe description of responseCode, carried alongside it for display. It is not a key: match on the code.
increasePinTryCount
Increments the PIN attempt counter for a given credit card. Takes a request containing the channel, the card's shadow number, and the increment value. Calls the underlying CRDPinServiceProxy to update the count.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
increasePinTryCount › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card the operation acts on, by its shadow card number — the platform's own reference, not the PAN.
increaseCountHow many tries to add to the card's PIN try count. Negative and zero are refused separately, each with its own code, so the smallest value this operation accepts is 1.
increasePinTryCount › Responses
Success
changeRsaPin
Changes the RSA PIN for a credit card. Validates the customer and card status to ensure there are no payment issues or problematic configurations. Returns the encrypted PIN, success status, and response details from the RSA service.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
changeRsaPin › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card the operation acts on, by its shadow card number — the platform's own reference, not the PAN.
currentEPBThe encrypted PIN block holding the cardholder's current PIN.
Its size follows the block format and the key it was built with rather than a column.
newEPBThe encrypted PIN block holding the PIN being set.
Its size follows the block format and the key it was built with rather than a column.
operationDateOfCurrentThe date the current PIN block was produced under. It belongs with currentEPB — the pair is what the key management service verifies.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
operationDateOfNewThe date the new PIN block was produced under, paired with newEPB the same way.
A date and time as a string, in RFC 3339 form: 2026-10-16T14:30:00Z, or with an offset, 2026-10-16T17:30:00+03:00.
changeRsaPin › Responses
Success
successWhether the operation did what it was asked to. A false here arrives with HTTP 200, so it has to be read rather than inferred from the status.
encryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
responseCodeThe downstream system's own result code, passed through. 00 and 0 are success; anything else is its refusal, and responseReasonCode or the description says which.
responseDescriptionThe description of responseCode, carried alongside it for display. It is not a key: match on the code.
verifyCardVerificationValue
Verifies the provided card verification value (CVV) against the stored CVV for the given card.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyCardVerificationValue › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card whose CVV is being checked.
verificationValueNotNull · LengthNotEquals — The CVV to check. Exactly 3 characters; any other length is refused before the card is read.
verifyCardVerificationValue › Responses
Success
verifiedWhether the CVV matched. A CVV that does not match is not an error — the call returns 200 with this false and the card's failed-attempt counter goes up. The counter is not in this response: the service behind it returns the count and whether the maximum was reached, and this API does not pass either on. Enough failures lock the card, and the next call is then refused with 1156 before the CVV is looked at.
generateCardVV
Generates the Card Verification Value (CVV) for a given credit card using shadow card number, BIN, clear PAN, expiry date, and key derivation index. Returns the CVV and error information if any.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
generateCardVV › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card to generate a verification value for.
keyDerivationIndexWhich key the card's encrypted values were produced under. Returned with the card; a caller does not choose it.
binThe bank identification number — the leading digits of the card number that name the issuer and the product range.
expiryDateStrThe card's expiry as MMYY.
clearPanA card number is not stored by these services; the platform keeps a shadow card number instead.
generateCardVV › Responses
Success
hasErrorTrue when the generator could not produce a value. It reports several of its own failures this way — a key it cannot use, a value it cannot derive — and the call still returns 200, so read this before verificationValue. It is also true when the generator answers nothing at all.
errorTextThe error in words, for a log or a screen rather than for matching.
verificationValueThe card verification value. Computed and compared rather than stored, and returned only where the operation is entitled to it.
verifyPartialCardVerificationValue
Verifies the partial card verification value (CVV) based on the provided number of digits for the given card.
Part of:
- Journey 02 · Managing a card product — step 3, PIN and verification
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyPartialCardVerificationValue › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card whose CVV is being checked.
NotBetween — The positions to check, as position/value pairs. Two or three pairs, no more and no fewer. Each position is 1 to 3 — the CVV is three digits — and each value is 0 to 9.
verifyPartialCardVerificationValue › Responses
Success
verifiedTrue only when every pair sent matches. The service generates the card's CVV and compares the positions given, so a wrong position is a mismatch rather than an error.
resetCvvCounter
Resets the CVV (Card Verification Value) counter for a specified card, based on the provided shadow card number.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
resetCvvCounter › Request Body
channelThree-digit code identifying the channel on behalf of which the request is made (e.g. 002 for Internet). Mandatory in every request. Used for entitlement checks, limit enforcement and audit logging. Channel codes are managed through configuration parameters and may change over time. Refer to the Channels page for the current list of valid codes.
shadowCardNumberThe card the operation acts on, by its shadow card number — the platform's own reference, not the PAN.
resetCvvCounter › Responses
Success