Facial capture (hosted link and FaceTec SDK)
Facial capture shows up in two products. In both, the person presents a live face; the difference is who opens the camera.
This guide covers both forms for account opening. Identity verification uses the same FaceTec SDK v10, with its own routes and quotas — requesting the package (bundle id, domain) is the same.
The app does not talk to FaceTec or Dracma. CorpX API does. Embedding the SDK without the package issued for your application fails at initialize (RejectedByServer): the binary identifier is not on the allowlist.
FaceTec is licensed by the tenant’s biometry provider. A zip from a FaceTec developer account does not authenticate CorpX sessions. Ask support for the package, with the identifiers below; CorpX returns the zip and registers the key.
Request the SDK
Write to suporte@corpx.com before embedding the camera. One package is valid for one application. Changing the bundle id, application id or domain after issuance requires a new request.
For each app (production and, if any, staging), send:
A React Native, Flutter or Cordova app sends both native identifiers (iOS and Android), because the binary the store installs is native. A PWA or your own page sends only the domains.
CorpX then:
- requests the FaceTec v10 package bound to those identifiers;
- delivers the zip (do not redistribute; the license is per application);
- for identity verification, stores
deviceKeyIdentifieron the tenant; - for account opening, the session key comes from
POST .../capture/{token}/start(sdk.key) — you still need the zip of that same version.
deviceKeyIdentifier is not a secret: it is embedded in the app and returned on the identity-verification 201. What must not leak is the zip, nor a bundle id different from the one you requested.
Without that record, method: facetec_sdk returns 403 facetec_sdk_not_enabled. The hosted opening page does not need the zip in your repo: it loads the Browser SDK from CorpX assets.
Platforms and languages
What FaceTec ships and what this flow accepts:
There is no C#, Python or Go package for the camera. The backend only relays requestBlob / responseBlob.
The SDK UI is available in 30+ languages (FaceTec localization). CorpX’s hosted page loads FaceTecStrings.pt-br.js and speaks Brazilian Portuguese to the holder. In your own app, use the FaceTecStrings.{locale}.js from the zip and FaceTecSDK.configureLocalization. A new package request does not change the language: that is a strings file, not a key.
The version must be v10. The old protocol (v9: faceScan / scanResultBlob, PEM, productionKeyText) does not work on these routes. For opening, sdk.version from /start is the asset version (currently the 10.1.x line); use exactly that zip.
On the Browser SDK the camera only opens on https (or localhost on a development zip). Remote HTTP fails with GetUserMediaRemoteHTTPNotSupported. A WebView needs the native platform camera permission, not just the page’s.
Opening: capture via the link
Use this when you do not control the device — WhatsApp, e-mail, a simple webview, desktop onboarding.
Do not send a biometry object. The 201 from POST /v1/accreditations/pf or /pj includes the link on the person who captures (for a company, only the administrator):
Give biometryLink only to that person. The token in the path is the credential: no JWT, valid for 24 h, and a POST /v1/accreditations/{id}/capture (or the person’s retry) invalidates the previous one.
The holder taps Iniciar verificação facial. The page loads the Browser SDK from /v1/accreditations/capture/assets/{version}/core-sdk/…, asks for the camera, relays the blobs and, at the end, calls GET .../done. That route re-reads the verification and sends the browser back to your callbackUri with outcome:
outcome picks a screen. Authoritative state still comes from the onboarding webhook and GET /v1/accreditations/{id}.
Whoever reopens the same link after completion sees the result, not the camera. With no registered callbackUri, the page shows the result and stops.
Opening: capture via the SDK in your app
Use this when the holder is already in your iOS, Android or web app and you want the camera there, without leaving for CorpX’s browser page.
1. Capture token
While the accreditation is PENDING_BIOMETRY:
captureUrl is the hosted page, if you want to fall back to it. In the app, what matters is captureToken: it goes in the path of the public routes below. Do not send a JWT on them. Each issue wipes the previous token. Outside PENDING_BIOMETRY, the response is 409 capture_not_available.
2. Initialize the SDK
When you are about to open the camera — not at app boot:
Load the zip for that sdk.version. On Browser SDK v10:
FaceTecSDK.setResourceDirectory/setImagesDirectoryfor the zip folders (core-sdk/FaceTecSDK.js/resources,core-sdk/FaceTec_images);configureLocalizationwith theFaceTecStringsfor the locale;initializeWithSessionRequest(sdk.key, processor).
The processor implements onSessionRequest(requestBlob, cb) and onFaceTecExit. Init already produces a requestBlob and counts toward the 15-call cap. Keep sessionToken in your backend and echo it on every /session; SDK v10 does not expose a session id to the app.
On iOS/Android the sample app in the zip shows the equivalent (initialize + session request). The CorpX wire is the same: every blob goes to /session.
3. Relay each blob
requestBlob and sessionToken are required. Body up to 5 MB (413 payload_too_large).
Optional headers, only if your SDK produces them:
X-FaceTec-User-Agent—FaceTecSDK.createFaceTecAPIUserAgentString("");X-Testing-API-Header—FaceTecSDK.getTestingAPIHeader(), on development zips.
The API only forwards them. Do not invent a value.
200 response:
Hand responseBlob back to the SDK (processResponse on the Browser SDK). status:
pending— handshake or capture with no verdict; does not count as a failed attempt; the SDK asks for another round;- any other value (
approved,rejected, …) — there was a verdict;rejectedcounts toward the 3 failures.
Do not interpret the blob. Do not call the provider.
When the SDK session ends with a verdict, send the holder to GET /v1/accreditations/capture/{token}/done (webview) or poll the accreditation / webhook. /done is the same as the hosted page: it re-reads the verification and returns outcome on callbackUri.
Link limits
A retry of the person (PF) or of the administrator (PJ) issues a new token. A partner who is not the administrator gets 422 administrator_required.
Identity verification
A billed API, independent of a bank account. POST /v1/identity-verifications with method: link returns verificationLink (the provider’s page). With method: facetec_sdk (requires provider: dracma_trust and the registered package) the 201 carries facetec.deviceKeyIdentifier and facetec.sessionToken; each capture goes to POST /v1/identity-verifications/{id}/facetec/process.
Requesting the zip (bundle id, application id, domains) is this Request the SDK section. The in-app protocol — initializeWithSessionRequest, requestBlob / responseBlob, 3 attempts, 15 calls, 10-minute token — lives in the identity verification guide. Do not mix the routes: opening capture does not call /facetec/process; identity verification does not use /accreditations/capture.
What not to do
- Call FaceTec or Dracma with the
sessionToken/sdk.key. The session is only valid on CorpX routes. - Reuse a zip from another application, another tenant or a free FaceTec developer account.
- Change the store bundle id and keep the same zip.
- Treat
callbackUri/outcomeas proof: the webhook and theGETclose the state. - Translate the API
errorCodeinto a generic one. The screen needs the original code (capture_expired,facetec_sdk_not_enabled, …). - Log
requestBlob,responseBlob,sessionTokenor a selfie.