PayXpert - User documentation
Remote Key Injection - Partner guide
This guide teaches PayXpert’s Terminal Fleet Manager partners how to remotely inject keys on their Sunmi payment terminals. Production keys are needed on the device in order for your merchants to start accepting payments with Payxpress.
Remote Key Injection (RKI) can be considered a preferred method over Local Key Injection (LKI) because you do not need to have the physical device in front of you in order to inject the keys. Also, it negates the need for the additional key encryption/injection hardware. Keys can be injected remotely in batches, which is easier than doing it one physical device at a time. Finally, the PCI PIN certification which is required for LKI is not necessary in the case of RKI.
Each key is unique on the individual POS devices but these keys are derived from the Base Derivation Key (BDK) that we will allocate to you as the maintainer.
Architecture
There are three architectural components of the Partner RKI solution:
An HSM provider which Sunmi uses to generate encrypted keys. The Initial transport key (ZMK) shared securely between PayXpert’s own HSM provider and Sunmi’s HSM is stored there. Sunmi has HSMs in both in China and in Europe.
An RKI Server: A Sunmi server that stores the keys and sends them to your devices
The Sunmi MDM portal: the UI by which you as a Terminal Fleet Manager will perform the actions to inject the keys stored on the RKI server
How it works - Overview
First, you must add PayXpert as a “partner”. We will then accept your friend request, assigning your organization a Base Derivation Key (BDK), and you will then be associated with us and you will be able to inject keys and maintain your POS devices.
Then, you (as the manager of your fleet) must trigger a “key assignment” action via the online portal. This will check the request against the Base Derivation Key assigned to your organization, and if okay, the RKI Service will create derived keys and they’ll be available on the server for manipulation.
You can then deploy those keys (this is called a “Download Task”) by selecting which devices to inject them on:
(keys being pushed to your stock)
Note that the Sunmi Key Injection App—specifically version 2.x.x, for the European Sunmi portal—must be installed on the device. Otherwise, it cannot properly receive the key. If using the Chinese Sunmi portal then this specific, higher version of Key Injection App is not required (you can just use version 1.x.x).
The correct key will enable Payxpress, if not installed already, to process payments on the devices when installed.
Once the POS has received the key, it will send an acknowledgment back to the RKI Server and you will be able to see in the UI that a valid key is live on the device. Note that it must be powered on and connected in order for this to work. It should also already have the latest firmware, so before injecting keys please be sure the device has both the Key Injection app and the correct ROM for that particular device.
You can then ship the devices from your warehouse to your merchants' sites.
Add us as a “Partner”
Once you get access to the Sunmi portal, please add PayXpert as a “Partner”. To do this:
Go to your Account page and click Add Partner.
Add us using our Entity ID: U9CLTOI0GYB53.
Please inform us when you have added us.
We will authorize you for RKI, assigning you a Base Derivation Key from which individual keys can be created.
How to create a Device Group
For the purpose of saving time when injecting keys it is interesting to have Device Groups. This concept will let you perform the RKI actions of assigning a key and starting the “Download Task” action for as many devices as you desire instead of handling each device one by one. Therefore we explain how to create a Device Group before we will explain how to handle an RKI.
It is useful to group devices before injecting keys onto them. To create a group of devices:
Go to the Device tab and click the button to create a + Device Group:
Enter a name (and description) for this group:
Now you can assign devices to the group. Hover over the name of the
new group and click the Add + button that appears:
In the window that appears you can add single or multiple devices to your group. Search for the Serial Number (manually, as shown below) or use the Sunmi template (download it first if needed) listing the SNs of your devices in order to batch add them into the group.
The device(s) are listed with their status. Click the Import button to assign
the listed devices to this group.
You now have a group of devices that you can inject keys on with one RKI.
How to remotely inject keys on a device or group of devices
Injecting keys on a device(s) is performed in two sets of actions: 1. assigning a master key, 2. creating a Download Task. The RKI Service will then know 1. which Base Derivation Key (BDK) to use to create the derived keys and 2. that it has to push this/these new (derived) key(s) it creates onto a specific device (or Device Group).
To do both of these, and therefore to inject the keys:
Go to the key management page within the Sunmi portal that you are currently using:
EU: https://partner.eu.sunmi.com/finance/KeyManagement
The initial page for working with keys
There you will see that the BDK key (the ‘key source’) has been authorized for you. From this key, which is stored by Sunmi, but which PayXpert has authorized for you, you will be able to trigger the creation (“assignment”) of derived keys for your devices.
Now go to the Key Assignment tab. By default the Sunmi portal shows you all your devices, even if they already have been assigned a key. The device’s group (if any) is not shown. Here, you can assign a key to a single device or to a whole group.
(If assigning a key to a single device) There are 2 ways to assign a key to a single device:
By selecting the device:
Find the device on which you want to inject a key. Click Assign key.
In the window that appears, assign the master key by which the key for
this device will be derived:
Manually (for a single device):
Click the Assign Key button:
Select the single device by its Serial Number (SN) and select the Base Derivation Key (BDK) from which the RKI Service will derive a new, unique key for this device.
(If assigning a key to a group of devices) This is more practical if you manage
several devices:Click the Assign Key button:
Select the Device Group by its name and select the master key by which the
RKI Service will derive individual keys for all these devices in this group:
Your device (or Device Group) now has a key assignment. Now you need to create a “Download Task”, which is the real trigger for the RKI Service to use the Assigned master key to push a derived key onto that device (or device group) in the background.
To create a Download Task:Go to the Device Group (or single device). The device (or devices) should currently read “ready” (not locked), “assigned” (for the key) and should have “no task” currently associated with it/them.
Select all SNs in the group (or select an individual SN). Click the Create Download Task button.
A window appears showing you a preview of the Download Task.
Click Create Task to confirm the key injection.
An RKI for a single device can take a few minutes while for a larger group, a bit longer.
Remember that each device needs to be on and the Remote Key Injection app installed on each (v1.x.x if using the China portal, or v2.x.x if using the EU portal).
The Download Task is retried when a powered-off device is powered back ON. The Remote Key Injection is also retried when the service detects that an offline device has reconnected to the network.
Once a key has been injected, the device will appear as “locked.” It is necessary to unlock the device if you need to inject another key.
How to check if an RKI task has been completed successfully
Once you create a Download Task, the RKI Server will work in the background to create and send the derived keys to your device or Device Group. Depending on network speed and availability, and how many devices the key injection is taking place for, the task can take from a few minutes to a bit longer to complete.
While it is interesting to be able to check the progress of your RKI, it is always important to confirm that the injections have been completed. Therefore, we will show you how to check this.
To check the progress of a key Download Task that you have created, go to the Key Download Task tab. At the top of the screen you have a compact dashboard summing up the Tasks:
Notice that you can switch between the “Unfinished” and “Done” tabs to pinpoint devices on which the keys have not been successfully injected:
You can expand the Task to see the problem, in this case that the keys have not been downloaded at the device level:
Remember that if you click “Stop” to terminate a task, it will be moved to the “Done” tab, and will show “manually terminated”.
Complete history of RKIs
In the Key Download Record tab you can see a complete summary of all your past key injections: the SN of the device, the master key used, the type of key and type of injection (auto = from the RKI service, manual = from the RKI app on the individual POS device), whether the RKI was successful or not, and when the key was injected on the device (when the Download Task was returned by the device as finished).
Type of key | Explanation |
|---|---|
BDK | Base Derived Key: represents the secure key from which |
KEK | Key Encrypt/Exchange Key |
TMK | Terminal Master Key |
PIK | PIN Key |
MAK | Mac Key |
TDK | Account Data Encryption Key |
IPEK | DUKPT Initial PIN Encryption Key |
KPBK | Key Block Protection Key |
When you click on the View Key Derivation Record button, you can see the identifier of the (encrypted) key that is installed on a single device:
This will match the key record shown
on the actual device itself:
Troubleshooting “No injected keys” in Payxpress
This message can occur when there is no key on the device or when the wrong key remains on it, or if the key is remotely unlocked or unbound.
Before troubleshooting, please make sure:
you have triggered a “download task”
device is “unlocked”
the device is ON
the correct version of the Sunmi Key Inject app in installed on device
The device has the correct firmware version (see ROM FAQ)
If the payment app displays this message but from the SUNMI platform the keys look injected then we can go to our device and check the issue with the key that is injected on it.
On the Sunmi device:
Unlock the Security menu:
Settings > Security Center
Enter the password “SM9876@@“
Go to Advanced > Key Inject > RKI --> Key Inject. Normally, if there is a key that has been delivered to the device but not injected yet, this will solve the problem.
However, in our case, this will tell you the specific error concerning the key.
Error | Meaning | Reason | What to do |
|---|---|---|---|
-3000 | Debug key remains on POS
| Switching to debug after key injection will make the keys unavailable to use For security reasons a prod key will not work on devices in Debug mode | Delete the key from the POS:
Inject a new key:
|
-11208
| Device is locked | Device is locked because there is already a key assigned, downloaded and locked on it. This is what happens if you try to “Inject key” over an existing key, even if it is the correct key. | Unlock it (via Sunmi MDM, remotely)
Inject a new key:
|
-1
| Key record not found | The remote key injection did not work even when trying to force a downloaded key locally | Notify Support |
For further troubleshooting, go to Advanced > Key Inject > RKI --> Key Query
Now you can see a screen with Index info to help you understand the keys:
A properly injected key (type DUPKT_IPEK, of key record type “KCV”) should be located in Index 1. If you do not see a key at index 1 (if it says “null”), you must re-inject a key that is derived from your organization’s BDK (Base Derivation Key).
No Production key in place
Note that:Production keys go to Index 1. Should not be “null”!
old (pre-MDM) Dev keys can exist on Index 1, occupying this Index with the wrong keys. If this is the case: delete the key on the device and re-inject.
Debug keys go to Index 8. In the image above we see the debug key record
Dev keys currently go to Index 4
More indexes:
9001: reserved for Sunmi’s HW certificate key
199:
0:
FAQ
Who will upload my devices to the portal?
PayXpert will batch-upload your devices to the Sunmi portal so that you will see them when logging in.
Who is responsible for injecting keys on my devices?
You, as the Terminal Fleet Manager of your Sunmi devices, are responsible for remotely injecting the keys on them.
What does it mean that the device is “locked”?
It means that there is already a Production key on it; it is locked to prevent the injection of new keys.
How will I be billed?
You will be billed on a per-key basis. The Sunmi RKI service business model is therefore based on the number of keys used in your fleet, plus any other arrangements you have made with PayXpert.
Where can I find the RKI app needed to be installed on each device?
You can find the RKI app on Sunmi’s Private App Store.
At the time of publishing this, the required version:
if using the Chinese portal (https://partner.sunmi.com/) is 1.x.x.
if using the EU portal (https://partner.eu.sunmi.com/) is 2.x.x.
What is the minimum firmware needed on my particular model?
At the time of publishing this, the required ROM needed is:
P2 LITE SE : 3.0.35
P2 SMARTPAD: 3.2.3
P3: 3.0.15
P3H: 3.0.4
P3KH: 3.0.6
Can I inject keys in bulk batches?
Yes, you can inject keys on a single device or on a group of them. See How to create a Device Group to see how to take advantage of this feature.
How long can a device be powered OFF before rejecting the key download when powered back ON?
By default, the device should be turned on within 30 days of the creation of the Download Task. However, we can set this to a 180 day maximum if needed.