PIN and card security
Set and change a PIN, manage the try counter, and generate or verify the card verification values.
changeCardPin
Changes the PIN of a prepaid card.
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
encryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
changeRsaPin
Changes the RSA PIN for a prepaid card.
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.
operationDateOptional — Not read by the service. The facade's mapping of this field is commented out, so what is sent never leaves this API. setRsaPin and verifyRsaPin both forward their own operationDate; this one is the exception, and the field is published on all three.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
currentEPBRequired in practice — The current PIN, as an encrypted block. Not validated here; the prepaid PIN service verifies it before the change is made, so a change is a verification and a set in one call.
Its size follows the block format and the key it was built with rather than a column.
newEPBRequired in practice — The encrypted PIN block. Not validated here — the facade forwards it to the prepaid PIN service, which is where the block is decrypted and the rules are applied. Neither this API nor that service is given a clear PIN on this path.
Its size follows the block format and the key it was built with rather than a column.
changeRsaPin › Responses
Changed, if success says so, and a false covers both a refusal and an unanswered call — as on setRsaPin.
The current PIN is verified as part of this, so a wrong currentEPB is subject to the same try counter that verifyRsaPin reports on.
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.
generateCardVV
Generates the card verification value (CVV) for a prepaid card.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
generateCardVV › Responses
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.
This one fails closed, where the rest of this API fails open. hasError defaults to true when the PIN service answers with nothing, so an unanswered call reads as an error rather than as a success — the opposite of the PIN verifications beside it.
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.
increasePinTryCount
Increases the PIN try count for a prepaid card.
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.
increaseCountRequired in practice — How far to move the counter. The caller supplies the step — this is not a fixed increment of one, and nothing in this API bounds the value.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
increasePinTryCount › Responses
Moved. This operation returns no body: there is nothing to read but the status, and the resulting counter is not reported. Read it back with a verification or the PIN operation history if it matters.
Raising the counter past the card's limit is what blocks a card, so this is a write with a consequence rather than a diagnostic.
resetCvvCounter
Resets the CVV counter for a prepaid card.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
resetCvvCounter › Responses
Cleared. No body, as with the PIN counter.
The card verification value has its own counter, separate from the PIN's, and clearing it does not by itself lift a status a failed run of attempts put the card into. That is a status change, and it is changeCardStatus.
setCardPin
Sets the PIN for a prepaid card.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
clearPinRequired in practice — The PIN in the clear. Not validated here — it is forwarded to the prepaid PIN service, which applies the weak-PIN rules itself on this path rather than handing a list to the hardware security module. One rule, two paths; the encrypted path is setRsaPin.
Exactly 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
Set. The response carries the encrypted PIN and no success flag — unlike setRsaPin, this one has nothing to read as a result, so a refusal arrives as a failure rather than as a false.
Prefer setRsaPin where the channel can encrypt: this path puts a clear PIN in the request body.
encryptedPinThe PIN block as the key management service produced it. The PIN itself never travels.
verifyTerminalCardPin
Verifies the terminal-supplied PIN for a prepaid card.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
verifyTerminalCardPin › Request Body
clearCardNumberA card number is not stored by these services; the platform keeps a shadow card number instead.
pinBlockAn encrypted PIN block; its size follows the block format rather than a column.
Its size follows the block format rather than a column.
zpkA key the block travels under; its size is the key's.
tpkA key the block travels under; its size is the key's.
pinBlockFormatNames the block format rather than carrying data of its own.
verifyTerminalCardPin › Responses
Not implemented. The facade for this operation throws rather than doing anything. It is published because it is declared on the service contract, not because it works.
Verifying a prepaid PIN today is verifyRsaPin, or verifyCardPin where the channel cannot encrypt.
verifiedWhether the value presented matched the one held.
verifyRsaPin
Verifies the RSA PIN for a prepaid card.
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.
operationDateRequired in practice — The 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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
ePBRequired in practice — The encrypted PIN block. Not validated here — the facade forwards it to the prepaid PIN service, which is where the block is decrypted and the rules are applied. Neither this API nor that service is given a clear PIN on this path.
Its size follows the block format and the key it was built with rather than a column, so no length is published.
verifyRsaPin › Responses
A verification, and it can change the card. The response carries verified, the attempts remaining in lastTryCount and whether the limit was passed in tryCountExceed — and a wrong PIN that reaches the limit moves the card to a blocked status. An operation that reads like a query is one that writes.
An unanswered call still returns a filled body. The facade defaults every field of the response, so a PIN service that answers with nothing produces verified: false, tryCountExceed: false and lastTryCount: 0 — which is indistinguishable from a wrong PIN on a card whose counter has just been cleared. Treat a zero counter beside a false verification as a result to confirm rather than one to act on.
There is no static-salt variant on this programme. Credit publishes verifyRsaPinWithStaticSalt; the prepaid facade's equivalent is commented out in full, which is why no such path is published here.
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.
verifyPartialCardVerificationValue
Partially verifies the card verification value (CVV) of a prepaid card.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
digitsRequired in practice — The digits to check, as a list of pairs. Which half of a pair is the position and which is the digit is the prepaid PIN service's decision, and that service has not been read for this document — so the pairing is stated here as unknown rather than guessed. The facade forwards the list untouched.
verifyPartialCardVerificationValue › Responses
Checked, and the answer is verified alone — no counter and no limit flag, unlike the full verification beside it. Whether a partial check moves the counter is the PIN service's behaviour and is not visible from here.
verifiedWhether the value presented matched the one held.
verifyCardVerificationValue
Verifies the card verification value (CVV) of a prepaid 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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
verificationValueRequired in practice — The value to check, in the clear. Forwarded untouched; nothing here checks its length or shape.
A verification value is computed and compared rather than stored, so no column stands behind it.
verifyCardVerificationValue › Responses
Checked, against the card verification value's own counter — separate from the PIN's, with its own maximum, and reported in the same three fields. resetCvvCounter is what clears it.
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.
verifyCardPin
Verifies the PIN of a prepaid card.
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.
shadowCardNumberOne-of — The card to verify against. Send this or clearCardNumber: when this is empty the PAN is resolved to a shadow card number through the customer service first.
clearCardNumberOne-of — The card's PAN, used only when shadowCardNumber is empty. It is resolved to a shadow card number and the verification runs against that.
A card number is not stored by these services; the platform keeps a shadow card number instead.
clearPinRequired in practice — The PIN to verify, in the clear. Forwarded untouched; verifyRsaPin is the encrypted equivalent.
Exactly 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
A verification, and it can change the card — the same counter and the same blocking as verifyRsaPin, reported in the same three fields.
An unanswered call still returns a filled body. The facade defaults every field of the response, so a PIN service that answers with nothing produces verified: false, tryCountExceed: false and lastTryCount: 0 — which is indistinguishable from a wrong PIN on a card whose counter has just been cleared. Treat a zero counter beside a false verification as a result to confirm rather than one to act on.
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.
setRsaPin
Sets the RSA PIN for a prepaid card.
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.
operationDateRequired in practice — The date the PIN block was produced under. Forwarded with the block; the two are read as a pair. changeRsaPin publishes this field and does not forward it.
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.
shadowCardNumberRequired in practice — The card the operation acts on, by its shadow card number — the platform's own reference, not the PAN. Not validated here; an absent or unknown value is refused by the prepaid PIN service in its own vocabulary.
ePBRequired in practice — The encrypted PIN block. Not validated here — the facade forwards it to the prepaid PIN service, which is where the block is decrypted and the rules are applied. Neither this API nor that service is given a clear PIN on this path.
Its size follows the block format and the key it was built with rather than a column, so no length is published.
setRsaPin › Responses
Set, if success says so. The result is a flag rather than a status code: read success before treating the PIN as established.
A false here is not only a refusal. The facade defaults the flag to false when the PIN service answers with nothing, so success: false covers both a rule the PIN service applied and no answer at all, and the two look identical from here.
The weak-PIN rules this is subject to are the platform's, not this API's, and are the same on every programme — a list built from the cardholder's own data and checked in the hardware security module. They are stated once on the PIN capability page rather than repeated per operation.
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.
setCardPinViaSMS
Sets the PIN for a prepaid card via SMS.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
setCardPinViaSMS › Request Body
mobilePhoneNumberHanded to the SMS service rather than stored here. The platform prefixes 90 when it is given ten digits, which is the shape to send; it is not a maximum.
cardNumberLastSixDigitsThe first six digits of a card number, which is not itself stored by these services.
cVVLastTwoDigitsTwo digits of a verification value, which is never stored.
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.
setCardPinViaSMS › Responses
Not implemented. The facade for this operation throws rather than doing anything, with a note in the source saying the PIN management side is still to be built. It is published because it is declared on the service contract, not because it works.
Setting a prepaid PIN today is setRsaPin, or setCardPin where the channel cannot encrypt. Core banking publishes isSetCardPinViaSMSControl, which answers whether the SMS route is permitted — it does not make this one work.
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.
errorCodeThe platform's own code for the error, and what to match on.
customerNumberThe customer at the bank's core banking system, as a number. The platform stores it rather than issuing it, so it comes from the core.
errorTextThe error in words, for a log or a screen rather than for matching.
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.
cardRefNumberThe card reference, which identifies one issued card including its renewals. Returned by the create and listing operations alongside the shadow number.
getCardPinOperationHistory
Retrieves the PIN operation history for a prepaid card.
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