Skip to main content

Terminal Remote Key Injection

Overview​

RKI is the secure process of loading encryption keys into payment terminals without physical intervention. This process is essential for enabling secure payment processing on terminals.

Determining RKI Status​

The Terminal Status API returns an rkiRequired flag that indicates whether a terminal needs key injection. However, you can call the RKI Generate Keys API regardless of this flag's value.

Key Encryption Methods​

Stitch supports two types of key encryption regimes:

1. Symmetric Key Encryption​

In this method:

  • The Terminal Master Key (TMK) is pre-loaded on the terminal during manufacturing
  • The TMK is encrypted symmetrically by the manufacturer
  • The manufacturer provides the encrypted TMK to Stitch in advance

2. Asymmetric Key Encryption​

In this method:

  • A Key Block Protection Key (KBPK) is created by Stitch
  • The KBPK is encrypted asymmetrically using a public key provided by the terminal
  • The terminal's public key is validated against a Certificate Authority (CA) public key that has been imported into the Stitch platform

When using asymmetric RKI, you must provide a terminalCertChain parameter, which is a PEM-encoded certificate chain containing:

  • The terminal's public key certificate (first in the chain)
  • The chain of certificate authorities that signed the terminal's certificate
  • The last certificate must be signed by the CA that was imported into the Stitch platform

Key Generation Process​

When you call the RKI Generate Keys API, Stitch generates two Initial PIN Encryption Keys (IPEKs):

  1. A PIN IPEK for securing PIN data
  2. A SRED IPEK (Secure Reading and Exchange of Data) for securing card data

These keys are encrypted with the TMK and returned in TR-31 format (a standard format for secure key exchange).

Response Format​

For asymmetric RKI, the generated KBPK is:

  • Encrypted and digitally signed
  • Returned as binary data, typically encoded as Base64 in the API response
  • ASCII-encoded HEX format is also supported, depending on the Stitch platform settings

Confirming Key Injection​

After successfully importing the keys into the terminal, you must call the RKI Confirm Keys API to notify Stitch that the key injection is complete. This updates the rkiRequired flag in the system.