Nesta página
Antes de executar
Os comandos são exemplos sintéticos. api.example.invalid não é um ambiente de testes e não resolve como serviço real. Substitua a base somente pelo endereço confirmado para seu ambiente habilitado e mantenha a chave no backend. Para experimentar sem rede ou credenciais, abra o simulador.
1. Crie uma transação
Escolha uma chave de idempotência estável para a mesma tentativa de criação. O CPF abaixo é um valor fictício de documentação.
# 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.
2. Encaminhe a jornada
O POST retorna 201 e o identificador transaction_id. Guarde esse identificador junto ao seu external_id. Encaminhe a pessoa usando a URL hospedada retornada em links.webview_url; não construa links a partir do identificador da transação.
3. Consulte o resultado
# 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_TRANSACTION_ID:?Use the returned transaction_id}"
curl --fail-with-body --max-time 15 --request GET \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions/${KYC_TRANSACTION_ID}" \
--header "X-API-Key: ${KYC_API_KEY}"
# 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.
Leia status, decision e decision_reason em conjunto. Uma decisão pending ainda não permite concluir seu fluxo como aprovado. A consulta utiliza a chave do mesmo Tenant e ambiente da transação.
Próximo passo
Implemente webhooks com validação HMAC e reconciliação. Antes de produção, cubra rejeição, expiração, revisão manual, duplicidades e perda temporária de conexão.