API Docs · eKYC Core
Integration scenarios
Which eKYC Core endpoints you call, from where, and in what order. Start with the consent obligations, pick the topology that matches how much of the flow your own backend owns, then follow the interaction flow for each capability you need.
User Consent
Some of the APIs required user consent in order to process user's PII data.
To provide user consent for TS, client should attach the following headers to the request:
| header | required | description |
|---|---|---|
X-UC-IP | no | Current IP address of the end-user used during the verification |
X-UC-Location | yes | Current location of the end-user in format: <country-code>/<state-code> - Country of end-user. Possible values: ISO 3166-1 alpha-3 country code - State of end-user. Applicable only in countries where state exists, including USA. Possible values: For USA, CAN, or AUS alpha-2 code (state only - without country & hyphen), e.g. IL (Illinois), NSW (New South Wales). For other countries, if applicable, any string. For VNM & PHL, State is not mandatory. |
X-UC-Consent-Obtained | yes | Consent obtained from the end-user. Possible values: yes or no |
X-UC-Consent-Obtained-At | yes | Timestamp when consent was obtained from the end-user. Format: RFC3339, e.g. 2019-04-21T18:00:15+07:00 |
For the list of services that required user consent, please contact the admin.
Suggested scenarios (eKYC System included Face Authen services, NFC Chip verification services)
Scenario 1: Recommended
Mobile/Web App will send all requests to the Bank's Server. Bank's backend implements based on your business as call APIs (OCR, Liveness, FaceMatching, FaceRetrieval,..) to TrustingSocial Server and receives a response. And then handle the response and return the result to your application.
Scenario 2: Forwarding requests
Mobile/Web App will send all requests to the Bank's Server. The Bank Server attaches the authorization header and forwards all requests to the TrustingSocial Server.
eKYC result will be sent back to the Mobile/Web App
Scenario 3: Use temporary credential or signature
Mobile/Web App will call the Bank's Server to get temporary credentials or signature. Mobile/Web App will use a temporary credential or signature to call Trusting Social.
Temporary signature: Recommended
Scenario 4: Restrict with security
Mobile/Web App will call the TrustingSocial Server directly and receive the eKYC result.
Scenario Hybrid: Scenario 1 and Scenario 3
Mobile/Web App will upload images and video frames to the TrustingSocial Server directly. The Bank server will call main API services (OCR, Tampering, Liveness check, Compare Faces, Face Authen, NFC).
Suggested scenarios (FaceAuthen System deployed On-premise or Cloud)
Scenario 1: Recommended (FaceAuthen Standalone)
Mobile/Web App will send all requests to the Bank's Server. Bank's backend implements based on your business as calls APIs (Face Registration, Face Authentication) to TrustingSocial Server and receives a response. And then handle the response and return the result to your application.
Scenario 2: Face Authen Standalone combines with user onboarding eKYC on TS's eKYC system
Mobile/Web App will send all requests to Bank's Server. Bank's backend implements based on your business as call APIs (Face Registration, Face Authentication) to TrustingSocial Server and receives a response. And then handle the response and return the result to your application.
Interaction Flows
Flow 1: Compare faces between images
Flow 2: Verify face liveness in images
We provide multi-layered liveness detection - active (challenge response-based) liveness verification and passive (AI-based) liveness verification.
Flow 3: Read ID card info
Flow 4: Convert PDF to images
Flow 5: Verify portrait sanity
Flow 6: Verify id card sanity
Flow 7: Index faces
Flow 8: Search faces
Flow 9: Update metadata
Flow 10: Face OTP
API Reconciliation
To make easier for API reconciliation, we support some ways to reconcile requests between the client and TrustingSocial (TS) as below:
- Use X-Request-ID (Recommended for VN market): When the client makes any API should pass an HTTP header X-Request-Id. The client should generate and manage its value of it (max length 64 characters). When reconciling, we will compare the value that the client sent and TS received if have a mismatch Besides that, we often reconcile base users, so the client should generate a value for all APIs calls of a user.
eg. Client can generate pattern like: a UUID or [USER_ID]-[RANDOM_ID], ...
If a user has multiple sessions, you can use X-Request-ID2 to distinguish between sessions.
- Use both headers: X-Request-ID: [USER_ID] and X-Request-ID2: [SESSION_ID]
- Only use X-Request-ID: [USER_ID]-[SESSION_ID]
- Use Transaction-ID (Recommended for IN market): Reference API