Canal embebido
Belfort pone la interfaz de captura dentro de un iframe en tu producto. Tú creas la sesión desde tu backend, montas el widget con el clientSecret y recibes el veredicto por webhook — sin tocar biometría ni almacenar una sola imagen.
Hay dos formas de crear la sesión: desde tu backend con una sk_, o desde el navegador con una publishable pk_ cuando el flujo ya está fijado.
La pk_ viaja al navegador, así que no concede nada por sí sola: solo abre sesiones contra los allowedOrigins que configuraste.
init y policy no llevan credencial de integrador: los llama el propio widget con el token de la sesión.
Crear una sesión embebida
POST /v1/embedded/sessions
Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.
Desde tu backend, con tu clave secreta. Devuelve el clientSecret con el que montas el widget en el navegador de la persona.
Parámetros
x-service-key header |
|
Idempotency-Key header |
Cuerpo de la petición
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
no | string[] |
|
callbackUrl |
no | string (uri) | null |
|
checks |
no | CheckSelectionInput | null |
|
clientReference |
no | string | null |
|
country |
no | string |
|
flowId |
no | string | null |
Opaque flow id. |
locale |
no | string |
|
notificationsMode |
no | belfort_managed | integrator_managed |
|
personId |
no | string | null |
Opaque person id. |
policy |
no | PolicyOverrideInput | null |
|
testMode |
no | boolean |
DEPRECADO: el modo test/live lo fija el environment de la API key. Con una key live, test_mode=true devuelve 400. |
Respuestas
201 Successful Response — EmbeddedSessionCreateResponse
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
clientSecret |
sí | string |
|
expiresAt |
sí | string (date-time) |
|
id |
sí | string |
Opaque embedded session id. |
personId |
no | string | null |
Opaque person id. |
status |
sí | string |
Crear una sesión embebida desde el navegador
POST /v1/embedded/sessions/browser
Requiere una publishable key (belfort_{env}_pk_…) con scope embedded:create_session.
La variante client-side, para cuando no quieres un salto por tu backend. Usa la publishable key y solo acepta un flujo ya publicado, contra los orígenes que autorizaste.
Cuerpo de la petición
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
clientReference |
no | string | null |
|
country |
no | string |
|
flow |
no | string | null |
|
locale |
no | string |
Respuestas
201 Successful Response — EmbeddedSessionCreateResponse
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
clientSecret |
sí | string |
|
expiresAt |
sí | string (date-time) |
|
id |
sí | string |
Opaque embedded session id. |
personId |
no | string | null |
Opaque person id. |
status |
sí | string |
Inicializar el widget
POST /v1/embedded/sessions/init
Requiere una API key secreta (belfort_{env}_sk_…).
Lo llama el propio widget para canjear el clientSecret por su token de trabajo. No lo llamas tú.
Cuerpo de la petición
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
clientSecret |
sí | string |
|
parentOrigin |
no | string | null |
Respuestas
200 Successful Response — EmbeddedInitResponse
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
applicantToken |
sí | string |
|
expiresAt |
sí | string (date-time) |
|
requiresApp |
no | boolean |
|
sessionId |
sí | string |
Opaque embedded session id. |
status |
sí | string |
|
verificationSessionId |
sí | string |
Consultar la política del iframe
GET /v1/embedded/sessions/{session_id}/policy
Requiere una API key secreta (belfort_{env}_sk_…).
Devuelve las cabeceras de seguridad que el iframe debe respetar en esa sesión. Público a propósito: el navegador lo consulta antes de tener credencial alguna.
Parámetros
session_id path · requerido |
string |
Respuestas
200 Successful Response — EmbeddedPolicyResponse
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
frameAncestors |
sí | string |
|
sessionId |
sí | string |
Opaque embedded session id. |
Confirmar el resultado desde tu servidor
POST /v1/embedded/sessions/{session_id}/verify
Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.
Comprueba, desde tu backend, el estado final de una sesión embebida. Existe para que no tengas que confiar en lo que te diga el navegador.
Parámetros
session_id path · requerido |
string |
Respuestas
200 Successful Response — EmbeddedVerifyResponse
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
allowedOrigins |
sí | string[] |
|
biometricMatch |
no | BiometricMatchSummary | null |
|
clientReference |
no | string | null |
|
completedAt |
sí | string (date-time) | null |
|
createdAt |
sí | string (date-time) |
|
decision |
sí | EmbeddedDecisionSummary | null |
|
decisionMode |
no | string | null |
|
deviceTrust |
no | DeviceTrustSummary | null |
|
document |
no | DocumentSummary | null |
|
expiresAt |
sí | string (date-time) |
|
gov |
no | GovCheckWire[] |
|
humanReviewAvailable |
no | boolean |
|
id |
sí | string |
|
isFinal |
sí | boolean |
|
mountedAt |
sí | string (date-time) | null |
|
personId |
no | string | null |
Opaque person id. |
phase |
sí | processing | review | completed | failed |
|
reuse |
no | ReuseSummary | null |
|
status |
sí | string |
|
trustScore |
sí | number | null |
|
verificationStatus |
sí | string |