PIN and card security
Set and change a PIN, manage the try counter, and generate or verify the card verification values.
setCardPin
Sets or updates the PIN for a specific debit card. Accepts card reference number, channel, and new PIN details, and applies the changes to the card securely.
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 debit card using the current PIN and returns the status including encrypted PIN, success, and verification flags.
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 PIN of a card. Used to confirm cardholder authorization in debit channels.
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 card. Ensures secure cardholder authorization using RSA PIN.
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.
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.
setRsaPin
Sets the RSA PIN for a card. Used for secure PIN management in debit channels.
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.
changeRsaPin
Changes the RSA PIN of a debit card using current and new encrypted PIN blocks. Returns encrypted PIN, success status, and response details.
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 currentEPB was produced under; the two 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.
operationDateOfNewThe date newEPB was produced under, paired with it 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.
increasePinTryCount
Increases the PIN try count for a given debit card. Accepts a ShadowCardNumber, Channel, and IncreaseCount to increment the attempt counter via the debit PIN service proxy.
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, so the smallest value accepted is 1.
increasePinTryCount › Responses
Success
verifyRsaPinWithStaticSalt
Verifies the RSA PIN with a static salt. Provides additional security for cardholder authentication using salted RSA PIN.
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 — the only field separating this operation from verifyRsaPin.
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.
verifyCVV
Verifies the CVV of a card. Used for cardholder validation during transactions.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyCVV › 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.
verifyCVV › 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 value is checked against the card's current expiry date and, failing that, against its previous one, so a CVV that still matches the old expiry verifies.
lastTryCountThe failed-attempt counter after this call. Zero when the CVV matched, because a match resets it.
tryCountExceedTrue when this call took the counter to the platform's maximum. The next call is refused with 10508 before the CVV is looked at, until the counter is reset.
verifyCVVPartial
Partially verifies the CVV of a card. Used when partial CVV verification is required for transaction purposes.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyCVVPartial › 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.
verifyCVVPartial › 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.
generateCVV
Generates the CVV (Card Verification Value) for a given shadow card. Returns the verification value along with any error information. Uses the underlying debit PIN service.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
generateCVV › 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.
generateCVV › Responses
Success.
Not every failure is a 400. The generator reports several of its own — a key it cannot use, a value it cannot produce — by setting hasError with the reason in errorText, and the call still returns 200. Check hasError before reading verificationValue.
hasErrorerrorTextThe 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.
getCardPinOperationHistory
Retrieves the PIN operation history for a debit card based on ShadowCardNumber. Returns a list of GetCardPinOperationHistory items including ChannelType, InsertDate, OperationResult, OperationResultDescription, OperationType, and OperationTypeDescription. Uses _dcidRepository.GetCardPinOperationHistory to fetch the data.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getCardPinOperationHistory › Request Body
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.
getCardPinOperationHistory › Responses
Success.
Nothing in this request is validated, and no service stands behind it. The facade reads its own store directly rather than calling the debit pin service, so shadowCardNumber is a query parameter rather than a checked field: a card that does not exist returns an empty history, not a refusal.
resetCvvCounter
Resets the CVV attempt counter for a given shadow card. Accepts the channel and shadow card number as input. Used to allow further CVV attempts after limits are reached.
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