MineZeus AM service provides following APIs to payment host side.
- Request API token This is a assistance API which is used for requesting a valid API JWT token by providing API KEY. This API has to be invoked to get JWT token before starting to invoke other APIs
- Query SDK Information MineZeus provides the detail information of each MPoC SDK instance including SDK ID, SDK version and KEK X509 Certificate which can be used for top key loading.
- Query SDK Attestation Status MineZeus provides the status information of each MPoC SDK instance including the latest attestation result and timestamp
The further sections introduce the details of each above API.
Request API token
MineSec will assign and send unique API KEY for each customer. Payment host needs to use this API KEY to request a JWT token for API invocation. API "Request API Token " is used to request JWT token by using API KEY. Each JWT token is only valid for a certain time (usually 7 days). Payment host has to use this API again to renew JWT token when the current JWT token is expired.
Request
POST https://am.mspayhub.com/mpoc/sp/api/token (opens in a new tab)
Header
NULL
Body
{
"customerId":"XXXXXXXXXX",
"apiKey":"YYYYYYYYYYYYY"
}- customerId - String, Unique ID that MineSec will generate and assign to each customer. Each customer usually has and only has one customer ID. But MineZeus support customer to have multiple customer ID based on business demanding.
- apiKey - String, Unique API Key that MineSec assigns for each CustomerID. Each customer can have one or more apiKey for business demanding. Since API Key is the able to get all senstive data. It has to be protected well by customer itself.
Response
{
"msg": "success",
"code": 0,
"data": {
"token": "eyJhbGciOiJIUzI1NiJ9.*********************.uvQzAJkucds8l*****",
"expiredAt": "UTC0 Unix TimeStamp (milli-seconds)"
}
}- token - A JWT token taht's generated and signed by MineZeus.
- expiredAt - token expiration time.
Query SDK Information
For a registered MPoC SDK, MPoC application can read an unique ID via SDK interface. Once payment host receives this unique ID from application, it can query the detail information of the registered SDK via "Query SDK Information " API. This is very useful when payment host wants to do initial payment key loading since an unique valid X509 RSA Certificate ("KekCert") is inlcuded in the SDK detail information.
Request
POST https://am.mspayhub.com/mpoc/sp/api/info/{customerId}/{sdkId} (opens in a new tab)
- customerId - the unique customerId assigned by MineSec
- sdkId - the unique SDK ID that payment server receives from MPoC application
Header
- token - JWT token requested via API KEY.
Body
NULL
Response
{
"msg": "success",
"code": 0,
"data": {
"sdkId": "82f8a1ae2e231a38",
"deviceId": "",
"version": "1.10.106",
"state": "VALID",
"attestResult": "HEALTH",
"attestResultAdvice": "success",
"attestTime": 1691558572000,
"kekCert": "-----BEGIN CERTIFICATE-----
MIIFvDCCA6SgAwIBAgIEPplB6TANBgkqhkiG9w0BAQsFADCBhjEnMCUGA1UEAwwe
UlNBX01QT0NfU0RLX0NBX0NFUlQgMTEyNTAwNzg5MRQwEgYDVQQLDAtNaW5lU2Vj
IFImRDEQMA4GA1UECgwHTWluZVNlYzESMBAGA1UEBwwJU2luZ2Fwb3JlMRIwEAYD
VQQIDAlTaW5nYXBvcmUxCzAJBgNVBAYTAlNHMB4XDTIzMDgwOTA1MjI1MloXDTI0
MDgxMzA1MjI1MlowgZkxCzAJBgNVBAYTAlNHMRIwEAYDVQQIDAlTaW5nYXBvcmUx
EjAQBgNVBAcMCVNpbmdhcG9yZTEtMCsGA1UECgwkOTM5NDk3YTEtMjQ3ZS00Mzc0
LWE0OTMtY2JiYjU0Zjk5NDI2MRgwFgYDVQQLDA9jb20ubWluZXNlYy5hcHAxGTAX
BgNVBAMMEDgyZjhhMWFlMmUyMzFhMzgwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAw
ggIKAoICAQC1WyWkh/6YEA99r9IukGQOeqUGiuSqpUlXL/qH51zN5+M3sIVI3H+L
GQI4gSH28CbRioM2jHm/WRNtWUsv4KGQxx2h7Q2M1ooF0Be44OlDmcSayZvCIweJ
c3hP0sdwZpbba04hamo42VF5swYNYOxSY1wFWKQ6Uilz7l2zNag6jCxrkKOjB+eB
pmLFWGqnrv5/2cU7Fc1B1q6c3+zOv4pMGk9K5zfweWB04lt8PvDQSzz6eoloVK26
FCKL94qMPV32ZPmLEFFMUPoDu/4fSb4cVYgIyEJb5EXyr7FUDEtPGzY2R25Zw/nS
Zxc0+DYdZqTYl1UNTp8tw2SBUMbBn2PsBNkPHXubUVqf5eFPUBQyLs8S/gK7nxMD
XeSP59++yRsmgKYmCCNzDfO2OOHpu9TWXfvqUB/oRHbivs4i/5YuSGgWEdcmAudr
tz3/lT7FhN34rgkTgnpND001Zuky3meQCpxzcnox1yGEQ6U8WFB+1GGSqdZ2V8qs
UWQQ5O5157AAHDgQeuIQ9THjuIvd2zcRZc68ZvxLmIJuugD2Hcu6xvDdFVqmb0yG
SZKwf+TRLuJ8JFoczjKl6HIVNe4o5S9oQL4CkkQHsiJ3abRiXuLF6uHQoiVOsVv8
iQ9akje5n5pbbXgeMWcQGbNkxOFcWK6Q5yvzoc3Rbe08zcMj6MdqgQIDAQABox0w
GzAMBgNVHRMBAf8EAjAAMAsGA1UdDwQEAwIFIDANBgkqhkiG9w0BAQsFAAOCAgEA
eTyDMhSTf2kPZ1gOFbLGD49j9KypMEjCGpNT7Y7l0Cxy1drzpRJJJxoCR+AlhWQP
Qr16tzjmWgOwURgSwoeHtwRjoY2kryAe8htM5foQ56UCF6odQVUqDOilDQcyZzxw
EO/h9Ko/qgh8dJWClXv0GRtDOJUrOHDisrAcy0Bq2reVlrNcSex28Q8SF7FxiTX7
RPbNj+9mZ22BJyiMxKplG+ABkNT9CCwIVzh1VhRaLhrr81o2GwrGBuPwF1ZvHb7q
m0aW4n3Rvv2kSwjO0DKbhYg6ninuvE1OPvlns1OGsmKg2zjZ5KeoG+dA5pqMu8nD
0sr1NuAT8FvTEKVWBb9oxPlzNbPeWFURnQPrKio+XohNgQdRwksz+whQ8ptfUGqM
tEgu1D2GyQIPVGm3ZhUE/WP7HPgzcAfHj2P0E1mPIlYdOmr+u7VIw7fP7CQYFO+r
QfV3iBzeoRr7+LVFeZNsaOrrhpJ/jDL2QT0AHgqbow1angDZlQv+hxrd87PTEp4j
CkbUNfC7woztu4JOK5EwCrjq4onwX1ZUpzfuRnSq45yDVDC8jXsvXVbMicGgp+rg
N2ghUpjRmSr4Dyu4GZR0KSkMg4JHr269DFzMzn3N2DiF4XykD/KeA208qsOTrOnE
SeMw/xhO5R1ImK/B+loL/UvRQWg1DE1pp+mbyxtjyhc=
-----END CERTIFICATE-----"
}
}Each property of the data object is described below.
| Property | Description | Comments |
|---|---|---|
| sdkId | Unique ID of MineHades SDK Instance | |
| deviceId | Reserved | |
| version | SDK Instance Version | |
| state | Indicate if SDK | It can be either VALID or INVALID *Note: state=INVALID case by device 1-block, 2-keys revoked, 3-sdk decommissioned * |
| attestResult | Latest Attestation Result | |
| attestResultAdvice | The advice for failure attestation result | It should be empty when attestResult is 'HEALTH' |
| attestTime | Time of latest attestation of SDK | Unix Timestamp UTC0 |
| kekCert | X509 RSA Certificate | It's signed by RSA_MPOC_SDK_CA_KEY |
Query SDK Attestation Status
MineZeus allows payment host to quickly request the SDK status by providing sdkId. This is useful when payment host needs to check the security status of SDK before performing senstive services (e.g. authorize a pay reuqest)
Request
GET https://am.mspayhub.com/mpoc/sp/api/security/{customerId}/{sdkId} (opens in a new tab)
- customerId - the unique customerId assigned by MineSec
- sdkId - the unique SDK ID that payment server receives from MPoC application
Header
- token - JWT token requested via API KEY.
Body
NULL
Response
{
"msg": "success",
"code": 0,
"data": {
"sdkId": "82f8a1ae2e231a38",
"deviceId": "",
"version": "1.10.106",
"state": "VALID",
"attestResult": "HEALTH",
"attestResultAdvice": "success",
"attestTime": 1691558572000
}
}Each property of the data object is described below.
| Property | Description | Comments |
|---|---|---|
| sdkId | Unique ID of MineHades SDK Instance | |
| deviceId | Reserved | |
| version | SDK Instance Version | |
| state | Indicate if SDK | It can be either VALID or INVALID *Note: state=INVALID case by device 1-block, 2-keys revoked, 3-sdk decommissioned * |
| attestResult | Latest Attestation Result | |
| attestResultAdvice | The advice for failure attestation result | It should be empty when attestResult is 'HEALTH' |
| attestTime | Time of latest attestation of SDK | Unix Timestamp UTC0 |