Skip to navigation

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.

ProductWhenCapture via linkCapture via SDK in your app
Account opening with centralized biometryPF/PJ onboarding, off by defaultpersons[].biometryLink opens the hosted pagePOST /v1/accreditations/{id}/capture and the app relays the blobs
Identity verification (billed separately)Prove the CPF before a sensitive actionmethod: link returns verificationLinkmethod: facetec_sdk and the app calls /facetec/process

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.

Do not download the SDK on your own

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:

FieldRequired forExample
Tenantalltenant-yourcompany
Productallaccount opening (accreditation_central_kyc) and/or identity verification (identity_verification_facetec_sdk)
Application Nameallthe name FaceTec uses on the package, e.g. Bank X iOS
Platformallbrowser, ios, android, react_native, flutter or cordova
Bundle IdentifieriOS and anything that ships iOS (React Native, Flutter, Cordova)br.com.banco.app (CFBundleIdentifier)
Application IDAndroid and anything that ships Androidbr.com.banco.app (Gradle applicationId)
DomainsBrowser SDK and WebViewapp.banco.com, onboarding.banco.com — production hosts, no path
Environmentallproduction and/or development

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:

  1. requests the FaceTec v10 package bound to those identifiers;
  2. delivers the zip (do not redistribute; the license is per application);
  3. for identity verification, stores deviceKeyIdentifier on the tenant;
  4. 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:

PackageApp languageWhere CorpX uses it
Browser SDK v10JavaScriptHosted opening page; PWA / your own site
iOS SDK v10Swift or Objective-CNative iOS 12+ app
Android SDK v10Kotlin or JavaNative Android 5+ app
React Native, Flutter, Cordovathe wrapper languagethe wrapper calls the iOS/Android SDK; ask for those sample-app zips

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.

HTTPS and the camera

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.

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):

{
"accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
"status": "PENDING_BIOMETRY",
"persons": [
{
"personId": "prs_3b1c9a7f2e4d",
"biometryLink": "https://tenant.api.corpx.com/v1/accreditations/capture/{token}"
}
]
}

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.

loop [each SDK blob] POST /v1/accreditations/pf or /pj 201 with persons[].biometryLink open the link GET /v1/accreditations/capture/{token} POST .../start sessionToken, sdk.version, sdk.key POST .../session (requestBlob) responseBlob, status GET .../done redirect to callbackUri with outcome Your system Holder Hosted page CorpX API

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:

outcomeMeaning
biometry_approvedIdentity approved at the provider
biometry_pendingCapture left and the provider is still consolidating — the usual case; wait for the webhook
biometry_failedRejected; the person can retry
biometry_expiredLink or verification expired; issue another
error/done could not read the verification; consult the accreditation GET

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:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/$ACR_ID/capture" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID"
{
"accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
"captureToken": "…",
"expiresAt": "2026-10-17T12:00:00Z",
"captureUrl": "https://tenant.api.corpx.com/v1/accreditations/capture/…"
}

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:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/start"
{
"sessionToken": "…",
"expiresAt": "2026-10-16T12:10:00Z",
"sdk": {
"version": "10.1.21",
"key": "…"
}
}

Load the zip for that sdk.version. On Browser SDK v10:

  1. FaceTecSDK.setResourceDirectory / setImagesDirectory for the zip folders (core-sdk/FaceTecSDK.js/resources, core-sdk/FaceTec_images);
  2. configureLocalization with the FaceTecStrings for the locale;
  3. 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

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/session" \
-H "Content-Type: application/json" \
-H "X-FaceTec-User-Agent: $UA" \
-d '{
"requestBlob": "<SDK base64>",
"sessionToken": "<sessionToken from /start>"
}'

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:

{
"responseBlob": "…",
"status": "pending",
"retryAllowed": true
}

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; rejected counts 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.

CapError
Token lasts 24 h410 capture_expired — issue another
3 processed and rejected captures422 capture_failed_limit
15 calls to /start+/session (including handshake)429 capture_call_limit
One call at a time409 capture_in_progress
Verification not stored yet409 capture_not_available (retry in a few seconds)
Accreditation not PENDING_BIOMETRY409 capture_not_available

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 / outcome as proof: the webhook and the GET close the state.
  • Translate the API errorCode into a generic one. The screen needs the original code (capture_expired, facetec_sdk_not_enabled, …).
  • Log requestBlob, responseBlob, sessionToken or a selfie.