Defina o processo que será verificado
Crie a transação com POST /v1/face-auth/transactions. Os campos obrigatórios são country_code e subject; dentro de subject, informe identity com type, number e country. Consulte os países e locales aceitos na referência, sem transformar a lista de idiomas do site na lista de valores da API.
# Server-side only. Configure KYC_API_BASE_URL with your authorized base (https://api.example.invalid is illustrative), and KYC_API_KEY privately. Never expose credentials in browser code.
set -eu
: "${KYC_API_BASE_URL:?Set authorized base}" "${KYC_API_KEY:?Set API key}"
: "${KYC_IDEMPOTENCY_KEY:?Persist the key for this creation intent}"
curl --fail-with-body --max-time 15 --request POST \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions" \
--header "X-API-Key: ${KYC_API_KEY}" \
--header "Idempotency-Key: ${KYC_IDEMPOTENCY_KEY}" \
--header 'Content-Type: application/json' \
--data-binary '{"country_code":"BR","external_id":"docs-example-0001","locale":"pt-BR","subject":{"identity":{"country":"BR","number":"00000000000","type":"CPF"}}}'
# Persist transaction_id and business correlation; use the returned links.webview_url. Read status, decision and decision_reason together. Reuse the SAME idempotency key AND original payload only for the same creation intent; never silently bypass a 409 conflict.
Correlacione sem duplicar dados
Use external_id para relacionar o processo no seu sistema. subject.tenant_subject_id identifica a pessoa na sua base. Eles têm funções distintas e não substituem o transaction_id retornado pela API.
source descreve sistema, integração e canal de origem. metadata permite contexto de negócio, com limite de 8 KB; evite dados sensíveis e informações desnecessárias. A expiração pode ser configurada por expires_in_minutes, respeitando o contrato; quando ausente, vale o padrão do Tenant.
Trate a resposta
O retorno documentado é 201, inclusive quando uma criação é recuperada por idempotência. Persista o identificador antes de encaminhar a pessoa para a jornada. Se a resposta se perder após o envio, repita a mesma criação com a mesma chave e o mesmo payload; não gere uma chave nova automaticamente.
callback_url, quando informado, define o webhook daquela transação; quando ausente, utiliza a configuração do Tenant. Veja idempotência e webhooks antes de colocar esse fluxo em produção.