Saltar al contenido principal
API docs by Redocly

BeTrust KYC API (6.0)

Download OpenAPI specification:Download

BeTrust: [email protected]

API de Verificación de Identidad Biométrica (KYC) de BeTrust.

Flujo de integración mínimo (3 llamadas):

  1. Generar Access Token (OAuth2 client_credentials).
  2. Crear transacción de verificación.
  3. Entregar el link de verificación al usuario y consultar el estado de la transacción.

Además, credential_information permite recuperar los datos del documento al finalizar.

Ambientes: Sandbox (-tst) y Producción. Los hosts de producción se entregan en el onboarding. No hay ambiente de QA expuesto al integrador.

Auth

Autenticación OAuth2

Generar Access Token

Emite un token Bearer mediante OAuth2 client_credentials. El client_id/client_secret los entrega BeTrust por ambiente.

Request Body schema: application/json
required
client_id
required
string
client_secret
required
string
grant_type
required
string
Value: "client_credentials"

Responses

Request samples

Content type
application/json
{
  • "client_id": "<tu_client_id>",
  • "client_secret": "<tu_client_secret>",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "<access_token>",
  • "token_type": "Bearer",
  • "expires_in": 7200,
  • "scope": "",
  • "created_at": 1781823641
}

Transacciones

Creación y consulta de transacciones KYC

Crear transacción KYC

Crea una transacción de verificación de identidad.

Scope requerido: engine.transaction.w

Todas las reglas de negocio del flujo se configuran aquí (vía metadata): tipo de liveness, verificación de documento, enrolamiento, antifraude, branding, etc.

Idempotencia. El mecanismo es el transaction_id único por company_id: reintentar la creación con el mismo par devuelve 409 Duplicated (no se crea otra transacción).

Authorizations:
bearerAuth
Request Body schema: application/json
required
transaction_id
required
string

Identificador de la transacción del lado del integrador. Único por company_id.

company_id
required
string
authorization_method
required
string
Enum: "kyc_register" "kyc_register_simple" "sms" "email" "fido2" "bioidentity"

Método de validación.

tries
integer >= 1
Default: 3

Intentos permitidos (> 0). Si se omite, se completa según authorization_method.

expiration
integer
Default: 600

Expiración del link en segundos.

webhook
string <uri>

URL de notificación de cambios de estado.

scope
string
user_id
string
client_id
string
creator_user_id
string
allowed_clients
Array of strings
nanoid
boolean

Si es true, genera un nanoid de 6 caracteres.

user_email
string <email>
link
string

Plantilla de link. Soporta placeholders {{transaction_uuid}} y {{nin}}.

object (Metadata)

Configuración del flujo. Requerida para ciertos authorization_method (p. ej. kyc_register requiere nin). Nota: los umbrales de score (match facial, prueba de vida, calidad de selfie, antifraude) no se configuran aquí; se ajustan a nivel de compañía y sus valores se definen con cada cliente.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "transaction_id": "order-12345",
  • "company_id": "201",
  • "authorization_method": "kyc_register",
  • "tries": 3,
  • "expiration": 600,
  • "webhook": "https://tu-dominio.cl/webhooks/kyc",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "resource": "Transaction",
  • "data": {
    },
  • "message": "Found"
}

Callback payload samples

Callback
POST: Notificación de cambio de estado (webhook)
Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "transaction_id": "string",
  • "company_id": "string",
  • "authorization_method": "string",
  • "active": true,
  • "complete": true,
  • "failed": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "verification_result": {
    }
}

Consultar transacción (estado)

Obtiene una transacción por su identificador.

Scope requerido: engine.transaction.r

El estado se interpreta con la combinación active / complete / failed (ver schema Transaction). El detalle del paso y del rechazo viene en step / issue_description (ver StepCode y IssueCode).

Authorizations:
bearerAuth
path Parameters
transaction_uuid
required
string

Acepta tanto el uuid como el nanoid de la transacción.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "resource": "Transaction",
  • "data": {
    },
  • "message": "Found"
}

Credenciales

Datos del documento verificado

Datos del documento verificado

Recupera los datos del documento de una transacción finalizada. Host: https://api-tst.trust.lat.

Authorizations:
bearerAuth
query Parameters
transaction_id
required
string

UUID de la transacción.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "resource": "User Credential",
  • "data": {
    },
  • "message": "Ok"
}