Primeiros Passos

A Verificação de Cartão de Pagamento é uma etapa do widget hospedado de identidade. Depois que o cliente fotografou o documento e tirou uma selfie, o widget pede o cartão de pagamento, frente e verso, na mesma sessão. O resultado que você já recebe da verificação de identidade também traz as linhas do cartão.

Esta página pressupõe uma integração de identidade funcionando. Se você ainda não tem uma, comece pelos Primeiros Passos de identidade.

Pré-requisitos

A etapa do cartão habilitada para o seu tenant. Peça ao seu contato na Inyo. Até que esteja, uma sessão que pede o cartão é recusada com 422.
Para o modo de tokenização, a chave pública do seu gateway no seu tenant, com a tokenização ativada. A Inyo configura as duas coisas; peça ao seu contato na Inyo.
A sua integração de identidade: Autenticação, um webhookUrl ou entrega por redirect, e a verificação de assinatura em Recebendo Resultados.

Dois Modos

Você escolhe o modo por sessão.

Modo	Requisição	O que o titular faz	O que você recebe
Somente verificação	`"paymentCard": {"capture": true}`	Fotografa o cartão, frente e verso	Linhas do cartão em `checks`: o cartão está em quadro, legível e genuíno, e o seu nome corresponde ao documento de identidade
Verificação e tokenização	`"paymentCard": {"capture": true, "tokenize": {}}`	Fotografa o cartão, depois confere e confirma os dados lidos dele	As mesmas linhas, mais uma que checa o token contra o cartão fotografado, e um bloco `paymentCard` com o token do gateway

No modo de tokenização o titular nunca digita o cartão em um formulário seu. Os dados são lidos das fotos no dispositivo dele e confirmados na própria tela do widget.

Etapa 1: Crie uma Sessão com a Etapa do Cartão

Obtenha um token como de costume — veja Autenticação — e adicione paymentCard a POST /v1/sessions:

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "userRef": "user-123",
  "delivery": { "mode": "webhook" },
  "paymentCard": { "capture": true, "tokenize": { "storeLaterUse": false } }
}'

A resposta é o sessionId e o widgetUrl de sempre. Todos os campos e as recusas estão em Sessões de Cartão.

Envie o widgetUrl como você já faz. O titular passa pelas etapas de identidade e depois pela etapa do cartão — veja Fluxo do Widget para o que ele vê.

Etapa 3: Receba o Resultado

A sessão termina uma vez e é entregue uma vez, pelo mesmo webhook ou redirect de qualquer sessão de identidade. Em uma sessão de tokenização, o resultado traz o token:

{
  "status": "completed",
  "checks": [
    { "name": "payment_card_token_match", "status": "passed", "group": "payment_card", "severity": "high", "reason": null, "detail": "the tokenized card matches the photographed card and the holder" }
  ],
  "paymentCard": {
    "token": "3b9f6c1e-8d2a-4f7b-9e5c-1a2b3c4d5e6f",
    "lastFour": "4242",
    "kind": "one_time",
    "recordedAt": "2026-07-31T14:04:41.112Z"
  }
}

Leia as linhas do cartão antes de usar o token: uma sessão de tokenização mantém o seu bloco paymentCard seja qual for a conclusão das checagens do cartão. Veja Checagens e Resultados.

Etapa 4: Use o Token

paymentCard.token é um token de cartão do gateway. Use-o com as APIs de pagamento do gateway exatamente como um token do próprio tokenizador do gateway, sob as mesmas regras de uso único e recorrente.

Trate Estes Casos Antes de Entrar em Produção

Caso	O que acontece	Veja
O titular esgota as tentativas do cartão	A sessão termina `failed`, sem bloco `paymentCard`	Checagens
Uma checagem do cartão falha depois que o token foi registrado	A sessão é concluída, o bloco está presente, e a linha diz o que falhou	Checagens
A tokenização é desativada para o seu tenant depois que um link foi enviado	A etapa do cartão desse link roda como somente verificação	Sessões de Cartão
Uma sessão sem `paymentCard`	Sem etapa do cartão, sem linhas do cartão	—

Próximos Passos

Sessões de Cartão — o objeto paymentCard por completo
Tratamento de Dados — o que chega ao Inyo360 e o que é guardado
Sandbox e Dados de Teste — testando a etapa do cartão