Checkify
Documentação para desenvolvedores

Verifique no seu painel administrativo.

Após a conclusão da incorporação no navegador, seu servidor deve verificar o resultado com uma chave API do site antes de permitir o cadastro, a finalização da compra ou qualquer ação protegida.

Verificação do servidor em 5 minutos

  1. Adicione o ícone de incorporação do navegador Checkify à sua página.
  2. O componente incorporado inicia a sessão Checkify e insere a referência de verificação no seu formulário.
  3. Seu servidor lê o valor do campo oculto.
  4. Seu servidor envia esse valor para POST /v1/qr/results/verify como request_id.
  5. Se as solicitações necessárias forem aprovadas, autorize a ação protegida.
  6. Nunca confie apenas no estado do frontend.

O campo oculto do formulário pode ser nomeado checkify_token, mas seu valor é o request_id Checkify.

Fluxo de ponta a ponta

1. Crie uma chave de site API

No painel de controle da sua empresa, abra Desenvolvedor Crie uma chave de site API para o site que você está integrando. Armazene-a apenas em variáveis de ambiente do servidor — nunca a envie para o navegador.

Utilizando a interface SDK?

Você não precisa chamar manualmente o método GET /v1/qr/pass/{PASS_ID}/start. O componente Checkify JavaScript inicia a sessão, recebe o request_id e o insere automaticamente no seu formulário.

Seu backend só precisa:

2. Receba o request_id no seu servidor.

O frontend SDK insere o request_id Checkify em um campo oculto do formulário após o usuário concluir a verificação. O nome padrão do campo é checkify_token — esse é o nome do campo, não um tipo de token separado. Envie o valor do campo para o endpoint de verificação como request_id.

A transferência de aplicativos móveis pode retornar o `checkify_request_id` na URL da página. O SDK lê esse valor ao carregar a página; seu servidor ainda verifica o mesmo valor de `request_id`.

Formulário POST do seu frontend

{
  "email": "user@example.com",
  "checkify_token": "56a57761-ff5b-42f0-9c97-6c13e223e017"
}

Verifique a solicitação do seu backend.

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "required_fields": [],
  "consume": true
}

Somente integração manual de frontend

3. Teste manual com cURL

Desenvolvedores de backend normalmente não chamam `/start`. Use esta seção apenas ao criar um frontend personalizado ou ao realizar testes sem o recurso incorporado. Coloque URLs entre aspas no zsh/bash para que `?` não seja interpretado como um padrão glob.

O cabeçalho Origin é obrigatório para /start.

O comando `pass start` só funciona a partir de um domínio de website registrado. Os navegadores enviam o `Origin` automaticamente; o cURL não. Envie `Origin` (ou `X-Checkify-Site-Url`) com um nome de host listado em Sites → domínios permitidos. O nome de host deve ser exatamente o mesmo — `checkify.me` e `www.checkify.me` são diferentes.

Problema de teste mais comum

Se /start retornar HTTP 403, seu ID de acesso ainda pode ser válido. A causa mais comum é que o domínio da solicitação não esteja listado nos domínios permitidos, ou que www.example.com esteja registrado, mas example.com tenha sido usado (ou vice-versa).

Utilize um site de teste dedicado e passe seu painel Checkify para testes de integração. As chaves do site API usam o prefixo csk_; não há um formato de chave de teste separado. Não teste com o checkout de produção até que você tenha confirmado os fluxos de sucesso e de recusa.

# Step A — start a session (replace PASS_ID and YOUR_REGISTERED_DOMAIN)
curl -sS \
  -H "Accept: application/json" \
  -H "Origin: https://YOUR_REGISTERED_DOMAIN" \
  "https://checkify.me/v1/qr/pass/chk_live_YOUR_PASS_ID/start?request_type=human"

# Response includes request_id and qr_url — open qr_url and complete verification

# Step B — verify on your server (after the user completes verification)
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "PASTE_request_id_FROM_STEP_A",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Use sua chave de site API somente na chamada de verificação. Conclua a verificação no aplicativo antes de ligar para verificar — caso contrário, você receberá o status pendente.

Declarações obrigatórias por caso de uso

Defina `required_claims` para corresponder à comprovação necessária para sua ação protegida. Os nomes das declarações devem corresponder ao que o Checkify aprovou para essa sessão de verificação. As verificações de idade usam `age_over_{N}` (por exemplo, `age_over_18`). Limiares dinâmicos de 10 a 110 são suportados quando o componente incorporado solicita o tipo de requisição correspondente.

Caso de uso Sugestões de reivindicações obrigatórias Notas
Substituição de bot/CAPTCHA ["human_verified"] Confirma que um usuário real concluiu o fluxo Checkify.
Conteúdo para maiores de 13 anos ou produtos voltados para o público jovem. ["age_over_13"] Use quando o seu Passe solicitar idade_acima_de_13_anos.
Conteúdo para maiores de 16 anos ou regras regionais de idade ["age_over_16"] Use quando o seu Passe solicitar idade_acima_de_16_anos.
Vape, álcool ou caixa para maiores de 18 anos ["age_over_18"] Ajuste a faixa etária ao seu produto e mercado.
Produtos com restrição de idade para maiores de 21 anos (quando aplicável) ["age_over_21"] Use quando o seu Passe solicitar idade_acima_de_21_anos.
Política de varejo do Desafio 25 ou mais rigorosa ["age_over_25"] Use quando o seu Passe solicitar idade_acima_de_25_anos.
Limite de idade personalizado ["age_over_N"] Use age_over_N onde N é de 10 a 110, de acordo com o tipo da sua solicitação de incorporação.

Tipo de solicitação de incorporação → declaração do servidor

O tipo de solicitação do navegador deve corresponder à declaração que você verifica no servidor.

Tipo de solicitação de incorporaçãoreivindicações_obrigatórias
human["human_verified"]
age_over_13["age_over_13"]
age_over_16["age_over_16"]
age_over_18["age_over_18"]
age_over_21["age_over_21"]
age_over_25["age_over_25"]
age_over_N["age_over_N"] (N = 10–110)

Campos obrigatórios opcionais

Além de `required_claims`, você pode exigir campos de identidade específicos aprovados (por exemplo, país ou faixa etária) quando sua integração os coletar. Passe os nomes dos campos em `required_fields` — se algum estiver faltando no resultado aprovado, a verificação retornará `verification_failed` com `missing_fields` em `error.details`.

4. Verifique a configuração do seu servidor.

Faça a requisição POST para /v1/qr/results/verify com a chave API do seu site antes de conceder acesso. Considere a referência do navegador (request_id ou token de pesquisa legado) como não confiável até que Checkify confirme o resultado.

POST https://checkify.me/v1/qr/results/verify
Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

{
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "required_claims": ["human_verified"],
  "consume": true
}

Você também pode enviar token em vez de request_id. A chave API tem escopo no seu site Checkify — você não envia o site_id no corpo da solicitação.

Exemplos de implementação

# checkify_token from your form POST is sent as request_id
curl -sS -X POST "https://checkify.me/v1/qr/results/verify" \
  -H "Authorization: Bearer $CHECKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
    "required_claims": ["human_verified"],
    "consume": true
  }'

Quando usar consumir

Use consume: true para ações protegidas finais — finalização da compra, cadastro, redefinição de senha, compra com restrição de idade, acesso a conteúdo protegido

Use consume: false somente para — testes, depuração ou verificações não definitivas em que o resultado precisa ser verificado novamente mais tarde

Para ações regulamentadas ou de alto risco, prefira `consumer: true` para que o mesmo resultado de verificação não possa ser reutilizado para múltiplas decisões protegidas.

Falha encerrada para ações regulamentadas

Se o seu servidor não conseguir acessar Checkify, não permita o pagamento com restrição de idade, acesso a jogos de azar, acesso a conteúdo adulto, compra de cigarros eletrônicos ou bebidas alcoólicas, ou outras ações protegidas sem uma confirmação do servidor.

Use tempos limite HTTP curtos (por exemplo, 10 segundos). Tente novamente uma ou duas vezes em caso de erros transitórios 5xx ou de rede e, em seguida, negue o acesso. Registre os incidentes no servidor e exiba mensagens seguras para o usuário. Não exponha detalhes internos de erros do Checkify aos clientes.

try {
  const verdict = await verifyCheckifyResult(requestId);

  if (!verdict.allow) {
    return res.status(403).json({ error: "Verification required" });
  }

  // Continue protected action
} catch (err) {
  console.error("Checkify verification unavailable", err);

  return res.status(403).json({
    error: "Verification is temporarily unavailable. Please try again.",
  });
}

Servidor SDKs e ferramentas

Use @checkify/server (npm) ou checkify-server (Python) para auxiliares de verificação tipada, ou chame POST /v1/qr/results/verify diretamente. Ainda não há uma especificação OpenAPI publicada — use os exemplos nesta página.

O pacote @checkify/server v1.0.0 foi publicado no npm. O pacote Python checkify-server é distribuído no monorepo Checkify SDK.

Janela de expiração do resultado

As verificações concluídas expiram após QR_RESULT_MAX_AGE_SECONDS (padrão de 900 segundos / 15 minutos). Após a expiração, a verificação retorna result_expired — solicitando ao usuário que verifique novamente.

Pontos de extremidade para consulta de status (interfaces personalizadas)

O JavaScript SDK gerencia o estado da sessão para incorporações padrão. Use-os somente quando você criar um frontend personalizado que chame GET /v1/qr/pass/{pass_id}/start manualmente.

Gerenciamento de respostas

Em caso de sucesso, Checkify retorna HTTP 200 com success: true e status: completed. Permita o acesso somente quando as declarações necessárias estiverem presentes (por exemplo, human_verified: true).

{
  "success": true,
  "status": "completed",
  "message": "Verification result confirmed",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "site_id": "YOUR_SITE_ID",
  "business_id": "YOUR_BUSINESS_ID",
  "approved_claims": {
    "human_verified": true
  },
  "approved_fields": [],
  "signed_result": {
    "payload": { "...": "..." },
    "signature": "...",
    "signature_algorithm": "EdDSA",
    "key_id": "checkify:default"
  }
}

Resultado assinado

O objeto `signed_result` permite que seu backend mantenha um registro de auditoria inviolável de que a Checkify aprovou a solicitação necessária no momento da verificação. A maioria das integrações precisa apenas do objeto `approved_claims`. Empresas regulamentadas ou de alto risco também podem armazenar o `signed_result` para fins de auditoria. Não armazene mais informações pessoais do que o necessário.

Se o cliente ainda não tiver finalizado a ação no aplicativo, Checkify retorna HTTP 200 com sucesso: falso e status: pendente. Negue as ações protegidas e solicite ao usuário que conclua a verificação.

{
  "success": false,
  "status": "pending",
  "message": "Verification is not completed yet",
  "request_id": "56a57761-ff5b-42f0-9c97-6c13e223e017",
  "approved_claims": {},
  "signed_result": null
}
CampoSignificado
successtrue quando a verificação for concluída e os requisitos forem atendidos
statuscompleted ou pending
approved_claimsAlegações Checkify aprovadas, por exemplo. human_verified: true
signed_resultCarga útil assinada opcional para trilhas de auditoria

cargas úteis de erro JSON

Quando a verificação não puder prosseguir, Checkify retorna HTTP 4xx/5xx com um corpo estruturado JSON. Verifique o error.code e registre os detalhes do erro no servidor. Retorne mensagens genéricas aos usuários finais.

{
  "success": false,
  "error": {
    "code": "verification_failed",
    "message": "The verification did not include all required claims.",
    "details": {
      "missing_claims": ["age_over_18"]
    }
  }
}
Código HTTP Significado Ação recomendada
missing_authorization401Nenhum cabeçalho de autorização foi enviado.Enviar autorização: Bearer YOUR_SITE_API_KEY somente a partir do código do lado do servidor.
invalid_token401Token de portador ausente, malformado ou não é uma chave de site válida API.Verifique a chave no painel de controle da sua empresa e armazene-a nas variáveis de ambiente.
expired_token401A chave do site API foi revogada.Crie uma nova chave de site API e alterne-a em seus servidores.
missing_required_field400 / 422O request_id ou token está faltando no corpo do JSON.Passe o request_id do campo oculto do seu formulário ou o token de pesquisa, caso sua integração ainda o utilize.
invalid_request_id400A referência não pôde ser analisada ou está vazia após a normalização.Certifique-se de que seu frontend envie o request_id Checkify sem alterações.
result_not_found404Não existe nenhuma solicitação de verificação para essa referência.Rejeitar a ação. O usuário pode ter adulterado o campo oculto ou enviado uma sessão antiga.
result_expired410A verificação foi concluída há muito tempo para que se possa confiar nessa ação.Peça ao usuário para escanear novamente e chamar o método de verificação com o novo request_id.
verification_failed403 / 409A verificação foi concluída, mas não atendeu às suas solicitações/campos obrigatórios, pertence a outro site ou já foi utilizada.Negar acesso. Inspecionar error.details para obter informações sobre missing_claims, missing_fields ou reason.
missing_required_claims403developers_server.err_missing_required_claims_meaningdevelopers_server.err_missing_required_claims_action
missing_required_fields403developers_server.err_missing_required_fields_meaningdevelopers_server.err_missing_required_fields_action
unknown_required_attributes400developers_server.err_unknown_required_attributes_meaningdevelopers_server.err_unknown_required_attributes_action
business_not_operational403A conta comercial está bloqueada, arquivada ou inativa.Contate o proprietário da empresa ou o suporte da Checkify. Não permita ações protegidas até que a conta esteja ativa.
validation_errors422O corpo da requisição JSON falhou na validação do esquema (HTTP 422).Inspecione o arquivo error.details.validation_errors em busca de mensagens de erro em nível de campo. Corrija os tipos request_id, required_claims ou required_fields antes de tentar novamente.
rate_limited429Muitas chamadas de verificação em um curto período de tempo.Tente novamente com recuo exponencial. Verifique apenas em ações protegidas, não em cada visualização de página.
server_error500+Checkify não pôde concluir a verificação devido a um problema temporário no servidor.Tente novamente uma ou duas vezes, depois encerre a sessão e registre o incidente.

Webhooks e verificação assíncrona

Atualmente, a verificação do servidor é síncrona: seu backend verifica o `request_id` quando o usuário envia a ação protegida. Para fluxos de finalização de compra, cadastro e controle de acesso, essa é a abordagem recomendada. Webhooks de verificação de uso geral não são necessários para integrações padrão. O GoHighLevel e outras integrações de parceiros podem usar configurações de webhook de saída separadas no painel de controle da empresa.

Erros comuns

Lembrete de segurança

Trate o campo oculto como uma referência não confiável, não como uma prova. Sempre verifique com a chave API do seu site no servidor antes de conceder acesso. Use consume: true Para ações pontuais, como cadastro ou redefinição de senha.

Próximos passos