Sino Connect

Documentation for China NFC eID for the various endpoints that we offer.

Should be used in conjuction with the SDK provided by Fill Easy, to read Chinese ID card data.

Clients retrieve the reqId from their mobile application after the NFC scan. Pass it to NFC Poll to retrieve the encrypted card data, and optionally pass the same reqId to Face Recognition Request to have the live face compared against the card portrait during Face Recognition Poll.

NFC Poll

post

Used in conjunction with the SDK that we provide.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

reqidstring · min: 1Required

Request ID from NFC scan

Responses

200

Success

application/json

messagestringRequired

Status message

tokenstringRequired

JWE encrypted token containing NFC data

400

Bad Request - Invalid input parameters

application/json

500

Internal Server Error

application/json

post/sino-connect/nfc/callback

POST /sino-connect/nfc/callback HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "reqid": "smth-ddddddd"
}

{
  "message": "text",
  "token": "text"
}

Face Recognition Request

post

Initialize a face recognition session by passing your redirect URL.

Returns a launch URL (open on a mobile browser) and a JWT token that you must keep for polling status. Use the returned url to open an in-app web view or the system browser on the phone. After the user completes or cancels the H5 flow, the browser is redirected to your provided callback URL.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

redirectstringRequired

Redirect URI after user authorization.

Browser: HTTPS URL to your website.

iOS: HTTPS Universal link

Android: Package name (com.filleasy.app)

Example: https://www.yourwebsite.com/callback

reqIdstringOptional

Optional request ID from the NFC scan (the same value passed to NFC Poll). When supplied, the live face captured during the liveness flow is compared against that card's portrait at Face Recognition Poll, and the match is returned there. Omit it for a liveness-only check.

Responses

200

200 Success

application/json

messagestringOptional

tokenstringOptional

urlstringOptional

post/sino-connect/face-rec/request

POST /sino-connect/face-rec/request HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "redirect": "https://google.com"
}

200

200 Success

{
  "message": "Success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJlZDBhYzNhNTg3ZTY0YTFiYTkwNmRlYTk1YzY1YTQyOSIsImlhdCI6MTc1NjgxMTMwMX0.Ve72SAY9Yg0vMvYBepH7UrByVU7ZD6rYfNOxmKGARPQ",
  "url": "https://eidlink.h5.livedetect.cn/capture.html?token=ed0ac3a587e64a1ba906dea95c65a429"
}

Face Recognition Poll

post

Used to poll for the face recognition result after user action.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

tokenstringRequired

Responses

200

200 Success

application/json

messagestringRequired

Status message

tokenstringOptional

JWE encrypted token. Decrypts to an object containing the captured faceImage (raw base64), livenessResult (the liveness verdict as readable text), and — only when a reqId was supplied to Face Recognition Request — similarityScore (the 0–100 face-match score between the live face and the NFC portrait) plus similarityResult: "Match" when similarityScore ≥ 45, otherwise "No match", or the compare error status if the comparison could not run.

202

Pending

application/json

post/sino-connect/face-rec/callback

POST /sino-connect/face-rec/callback HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 180

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJlZDBhYzNhNTg3ZTY0YTFiYTkwNmRlYTk1YzY1YTQyOSIsImlhdCI6MTc1NjgxMTMwMX0.Ve72SAY9Yg0vMvYBepH7UrByVU7ZD6rYfNOxmKGARPQ"
}

{
  "message": "text",
  "token": "text"
}