PIN and card security
Set and change a PIN, manage the try counter, and generate or verify the card verification values.
isSetCardPinViaSMSControl
Checks if a customer has any card eligible for PIN change via SMS and allows setting a new PIN for credit, debit, or prepaid cards. Validates mobile number, card last four digits, clear PIN, and bank key.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
isSetCardPinViaSMSControl › Request Body
mobilePhoneNumberFormat — The cardholder's mobile number. Ten digits are accepted: the facade prefixes 90 before it searches, so 5xxxxxxxxx and 905xxxxxxxxx find the same cardholder.
Handed 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.
cardNumberLastFourDigitsLength 4 — The last four digits of the card number.
The last four digits of a card number, which is not itself stored by these services.
isSetCardPinViaSMSControl › Responses
Success, and it does not mean a card was found.
isHaveAnyCard carries that. When nothing matches, the answer is the response this operation started with — isHaveAnyCard false, customerNumber 0 and shadowCardNumber an empty string — not an error. When more than one card matches, only the first is returned, and nothing in the response says there were others.
isHaveAnyCardcustomerNumberThe 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.
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.
getClearPanByShadow
Resolves the clear PAN (Primary Account Number) from a given shadow card number. Accepts GetClearPanByShadowRequest with ShadowCardNumber and returns GetClearPanByShadowResponse containing ClearPan. Internally calls _cisServiceProxy.GetCardInfoByShadowCardNumber(). Also provides GetCardInfoByClearPan which retrieves detailed card information by ClearPan, returning GetCardInfoByClearPanResponse with properties like Bin, CardRefNumber, ProductNumber, CardSeqNumber, CardType, CustomerNumber, EncryptedCardNumber, ExpiryDate, HashCardNumber, MainCardRefNumber, MainCustomerNumber, MaskedCardNumber, MaskedPanAlternative, OwnerSearchName, ShadowCardNumber, StatusCode, and StatusReasonCode.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getClearPanByShadow › Request Body
shadowCardNumberThe card whose PAN is read.
getClearPanByShadow › Responses
Success, and the answer is the card number in the clear.
That is the whole purpose of this operation and the reason to reach for another one wherever a masked or hashed form will do — getSecureCardByPan returns the tokenised forms and never the number.
clearPan comes back null, with a 200, when the shadow card number matches nothing. A null here is a miss, not a card without a number.
clearPangetCardInfoByClearPan
Retrieves card information for a given clear PAN (primary account number). Accepts GetCardInfoByClearPanRequest with ClearPan. Returns GetCardInfoByClearPanResponse containing Bin, CardRefNumber, ProductNumber, CardSeqNumber, CardType, ClearPan, CustomerNumber, EncryptedCardNumber, ExpiryDate, HashCardNumber, MainCardRefNumber, MainCustomerNumber, MaskedCardNumber, MaskedPanAlternative, OwnerSearchName, ShadowCardNumber, StatusCode, and StatusReasonCode.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getCardInfoByClearPan › Request Body
clearPanThe card's PAN, in the clear.
A card number is not stored by these services; the platform keeps a shadow card number instead.
getCardInfoByClearPan › Responses
Success.
The body is empty when the card is not found. Note what comes back when it is: clearPan is echoed into the response alongside the masked, encrypted and hashed forms, so this answer carries the card number in the clear and should be handled accordingly.
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.
expiryDateA 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.
mainCustomerNumberThe main customer of a corporate relationship, as a number. The employees and supplementary holders under it carry their own customerNumber.
hashCardNumberA one-way hash of the card number, for matching two records without carrying the number.
encryptedCardNumberThe card number encrypted under the platform's key, which is how it travels between services.
maskedCardNumberThe card number with its middle digits masked, as the platform stores it. It is a display form, not a key: operations take the shadow number.
binThe bank identification number — the leading digits of the card number that name the issuer and the product range.
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.
cardSeqNumberWhich chip on the card was used, where a customer holds more than one card on the same number.
statusCodeValues:
A— validB— pendingC— stolenD— cancelled by the bankF— fraudG— temporarily blockedI— cancelledL— lostM— cancelled by the customerT— corporate dummy
statusReasonCodeWhy the status is what it is.
clearPancardTypeValues:
C— creditD— debitP— prepaid
productNumberThe card product the card is issued on. Defined in the parameter tables; getCardProductList returns the ones a tenant may use.
cardRefNumberThe card reference, which identifies one issued card including its renewals. Returned by the create and listing operations alongside the shadow number.
maskedPanAlternativeA second masked form of the card number, masked differently for a channel that needs other digits.
mainCardRefNumberThe card reference of the main card. On a supplementary card this is the card it hangs from; on a main card it is the card's own reference.
ownerSearchNameThe cardholder's name normalised for searching — accents and case removed. It is not the name on the card.
getEncryptDataBlock
Encrypts a given data block using KMT service. Validates input DataBlock, retrieves encryption parameters from cache, calls _kmtServiceProxy.EncryptDataBlock() with KeyId, IV, and CBC mode, and returns GetEncryptDataBlockResponse containing EncryptedDataBlock.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
getEncryptDataBlock › Request Body
dataBlockClear data block to encrypt. Rejected when null, empty or whitespace. The facade applies no length, format or character check and forwards the value as given.
A cipher block rather than stored data; no column behind it.
getEncryptDataBlock › Responses
Success.
Neither the key nor the initialisation vector is part of the contract. The facade reads one parameter row out of its own cache — group IntegrationCoreBanking, sub-group EncryptDataBlockParams, parameter id ENCRYPTION_KEY_ID — and uses parameterValue1 as the key id and parameterValue2 as the initialisation vector. The cipher mode is hard-coded to CBC. Rotating the key is a parameter change plus a cache reload, never a request change.
Because the parameters come from a cache, a row added or changed in the database does not take effect until that cache is reloaded.
The key-management service's reply is reduced to its encrypted data block; anything else it returns is discarded.
Note the naming asymmetry with the decrypt operation: the value returned here is encryptedDataBlock, while the decrypt request field that consumes it is called encryptDataBlock.
encryptedDataBlockdecryptDataBlock
Decrypts an encrypted data block using KMT service. Validates that EncryptDataBlock is not null or empty, retrieves encryption parameters from cache, calls DecryptDataBlock on KMT proxy with KeyId, IV, and CBC mode, and returns the clear data block.
Headers
evrst-ptrnidCorrelation id for this request. Echo it in your own logs to trace the call through the platform.
decryptDataBlock › Request Body
encryptDataBlockEncrypted data block to decrypt, as returned by the encrypt operation in its encryptedDataBlock field. Rejected when null, empty or whitespace. The facade applies no length or format check and forwards the value as given.
A cipher block rather than stored data; no column behind it.
decryptDataBlock › Responses
Success.
The key and the initialisation vector are taken from the same cached parameter row as the encrypt operation — group IntegrationCoreBanking, sub-group EncryptDataBlockParams, parameter id ENCRYPTION_KEY_ID, with parameterValue1 as the key id and parameterValue2 as the initialisation vector — and the cipher mode is hard-coded to CBC. A block encrypted before the parameter changed cannot be decrypted after it changed.
Because the parameters come from a cache, a row added or changed in the database does not take effect until that cache is reloaded.
The key-management service's reply is reduced to its clear data block; anything else it returns is discarded.
clearDataBlock