Skip to content

Online PIN

To do an online PIN transaction, these parameters are mandatory:

PIN block format

Rapyd uses ISO 9564-1 Format 0 for PIN blocks.

Key types

Rapyd supports two PIN-encryption key schemes. Which parameters you send depends on how your terminal is keyed:

Key scheme What the terminal sends KSN required?
ZPK (Zone PIN Key) — fixed key PinBlockKeyIndex only No
BDK (Base Derivation Key) — DUKPT PinBlockKeySerial (the KSN) Yes

With a ZPK, every PIN block is encrypted under the same shared key, identified by its index — there is no KSN. With a BDK, the terminal derives a unique key per transaction (DUKPT) and identifies it with a Key Serial Number, described below.

Key Serial Number (KSN)

Terminals that use DUKPT (Derived Unique Key Per Transaction) key management encrypt each PIN block under a unique, single-use key derived from a Base Derivation Key (BDK). These terminals must send the Key Serial Number that identifies the derived key in PinBlockKeySerial. ZPK (fixed-key) terminals do not send a KSN.

The KSN is a 20-character hexadecimal value (10 bytes / 80 bits) following the ANSI X9.24-1 TDES DUKPT structure:

Part Size Description
Initial Key Serial Number 59 bits Identifies the BDK (Key Set ID) and the terminal (device / TRSM ID)
Transaction counter 21 bits Increments on every transaction so each PIN block is encrypted under a unique key

Send the full, unmodified 20-hex KSN exactly as produced by the terminal — do not trim, pad, or reformat it. Rapyd uses it to locate the correct BDK and to derive the transaction key when translating the PIN block. The 21-bit counter boundary is not aligned to a hex-digit boundary, so truncating the value will break PIN translation.

Example KSN: C9F9127DEB000540007A

Note

ZPK (fixed-key) terminals omit PinBlockKeySerial entirely and send PinBlockKeyIndex only.

Key exchange

The first step is to send Rapyd information about your key custodians, should be at least three. Please send the list to your implementation specialist at Rapyd.

The information needed for each custodian is:

  • Custodian number (1, 2 or 3)
  • Name
  • Mobile number
  • E-mail
  • Business address (street, postcode, country, etc.)

UAT

  1. We create ZMK (Zone Master Key) in 3 components and send you in an email.
  2. You import the ZMK into your HSM and confirm that the import was successful.
  3. We create and send you the PPK (Pin Protection Key) in an email encrypted under the ZMK.
  4. You confirm that the PPK import was successful.
  5. You can start sending PIN transactions in the UAT environment.

Production

  1. We create ZMK (Zone Master Key) in 3 components and each component is sent to the corresponding key custodian.
  2. You import the ZMK into your HSM and confirm that the import was successful.
  3. We create and send you the PPK (Pin Protection Key) encrypted under the ZMK.
  4. You confirm that the PPK import was successful.
  5. You can start sending PIN transactions in the PROD environment.