AMS API - MineSec Developer Docs

MineZeus™ AM service provides following APIs to payment host side.

Query SDK Information MineZeus™ provides the detailed 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.

Authentication

All API requests must include the following headers for authentication:

Header	Description
sp-customer-id	Unique Customer ID assigned by MineSec
sp-customer-api-key	Unique API Key assigned by MineSec for the corresponding Customer ID

curl -X GET "https://am.mspayhub.com/mpoc/sp/api/info/{customerId}/{sdkId}" \
  -H "Content-Type: application/json" \
  -H "sp-customer-id: {customerId}" \
  -H "sp-customer-api-key: {apiKey}"

Request API Token (Deprecated)

⚠️ This authentication method has been deprecated and is no longer supported. Please use the sp-customer-id and sp-customer-api-key headers described in the Authentication section above.

View deprecated documentation

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.
apiKey - String, Unique API Key that MineSec assigns for each CustomerID.

Response

{
  "msg": "success",
  "code": 0,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.*********************.uvQzAJkucds8l*****",
    "expiredAt": "UTC0 Unix TimeStamp (milli-seconds)"
  }
}

token - A JWT token that'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") and X509 RSA Certificate ("signCert") is included in the SDK detail information.

Request

GET 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

Content-Type - application/json
sp-customer-id - the unique customerId assigned by MineSec
sp-customer-api-key - the API Key assigned by MineSec

Body

NULL

Example

curl -X GET "https://am.mspayhub.com/mpoc/sp/api/info/{customerId}/{sdkId}" \
  -H "Content-Type: application/json" \
  -H "sp-customer-id: {customerId}" \
  -H "sp-customer-api-key: {apiKey}"

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
                    ...
                    ...
                    ...
                    SeMw/xhO5R1ImK/B+loL/UvRQWg1DE1pp+mbyxtjyhc=
                    -----END CERTIFICATE-----",
        "signCert": "-----BEGIN CERTIFICATE-----
                    MIIFSDCCAzCgAwIBAgIER74nXDANBgkqhkiG9w0BAQsFADCBhjEnMCUGA1UEAwwe
                    UlNBX01QT0NfU0RLX0NBX0NFUlQgMTEyNTAwNzg5MRQwEgYDVQQLDAtNaW5lU2Vj
                    ...
                    ...
                    ...
                    Ck7VXkJJEisf4v5K
                    -----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
signCert	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

Content-Type - application/json
sp-customer-id - the unique customerId assigned by MineSec
sp-customer-api-key - the API Key assigned by MineSec

Body

NULL

Example

curl -X GET "https://am.mspayhub.com/mpoc/sp/api/security/{customerId}/{sdkId}" \
  -H "Content-Type: application/json" \
  -H "sp-customer-id: {customerId}" \
  -H "sp-customer-api-key: {apiKey}"

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

Getting Start AMS Error Codes