> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# 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**.

| Product                                                                                         | When                                    | Capture via **link**                           | Capture via **SDK** in your app                                     |
| ----------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| [Account opening](/baas/guias/abertura-de-contas/visao-geral) with centralized biometry         | PF/PJ onboarding, off by default        | `persons[].biometryLink` opens the hosted page | `POST /v1/accreditations/{id}/capture` and the app relays the blobs |
| [Identity verification](/baas/guias/autenticacao/verificacao-de-identidade) (billed separately) | Prove the CPF before a sensitive action | `method: link` returns `verificationLink`      | `method: 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](mailto: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:

| Field             | Required for                                                     | Example                                                                                                          |
| ----------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Tenant            | all                                                              | `tenant-yourcompany`                                                                                             |
| Product           | all                                                              | account opening (`accreditation_central_kyc`) and/or identity verification (`identity_verification_facetec_sdk`) |
| Application Name  | all                                                              | the name FaceTec uses on the package, e.g. `Bank X iOS`                                                          |
| Platform          | all                                                              | `browser`, `ios`, `android`, `react_native`, `flutter` or `cordova`                                              |
| Bundle Identifier | iOS and anything that ships iOS (React Native, Flutter, Cordova) | `br.com.banco.app` (`CFBundleIdentifier`)                                                                        |
| Application ID    | Android and anything that ships Android                          | `br.com.banco.app` (Gradle `applicationId`)                                                                      |
| Domains           | Browser SDK and WebView                                          | `app.banco.com`, `onboarding.banco.com` — production hosts, no path                                              |
| Environment       | all                                                              | production 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:

| Package                        | App language         | Where CorpX uses it                                                  |
| ------------------------------ | -------------------- | -------------------------------------------------------------------- |
| Browser SDK v10                | JavaScript           | Hosted opening page; PWA / your own site                             |
| iOS SDK v10                    | Swift or Objective-C | Native iOS 12+ app                                                   |
| Android SDK v10                | Kotlin or Java       | Native Android 5+ app                                                |
| React Native, Flutter, Cordova | the wrapper language | the 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.

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

```json
{
  "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.

```mermaid
sequenceDiagram
  participant You as Your system
  participant Holder
  participant Page as Hosted page
  participant API as CorpX API

  You->>API: POST /v1/accreditations/pf or /pj
  API-->>You: 201 with persons[].biometryLink
  You->>Holder: open the link
  Holder->>Page: GET /v1/accreditations/capture/{token}
  Page->>API: POST .../start
  API-->>Page: sessionToken, sdk.version, sdk.key
  loop each SDK blob
    Page->>API: POST .../session (requestBlob)
    API-->>Page: responseBlob, status
  end
  Page->>API: GET .../done
  API-->>Holder: redirect to callbackUri with outcome
```

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`](/baas/guias/abertura-de-contas/callback-uri) with `outcome`:

| `outcome`           | Meaning                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `biometry_approved` | Identity approved at the provider                                                           |
| `biometry_pending`  | Capture left and the provider is still consolidating — the usual case; wait for the webhook |
| `biometry_failed`   | Rejected; the person can retry                                                              |
| `biometry_expired`  | Link 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](/baas/guias/abertura-de-contas/webhooks) 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`:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/$ACR_ID/capture" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

```json
{
  "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:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/start"
```

```json
{
  "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

```bash
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:

```json
{
  "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`.

### Link limits

| Cap                                                   | Error                                                |
| ----------------------------------------------------- | ---------------------------------------------------- |
| Token lasts 24 h                                      | `410 capture_expired` — issue another                |
| 3 **processed and rejected** captures                 | `422 capture_failed_limit`                           |
| 15 calls to `/start`+`/session` (including handshake) | `429 capture_call_limit`                             |
| One call at a time                                    | `409 capture_in_progress`                            |
| Verification not stored yet                           | `409 capture_not_available` (retry in a few seconds) |
| Accreditation not `PENDING_BIOMETRY`                  | `409 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](#request-the-sdk) section. The in-app protocol — `initializeWithSessionRequest`, `requestBlob` / `responseBlob`, 3 attempts, 15 calls, 10-minute token — lives in the [identity verification guide](/baas/guias/autenticacao/verificacao-de-identidade#capture-with-the-facetec-sdk). 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.