Sessões de Cartão

A etapa do cartão é pedida por sessão, com o objeto paymentCard em POST /v1/sessions. Todo o resto da requisição — userRef, prefill, delivery, language — é o da sessão de identidade, documentado em Sessões de Verificação.

Criar uma Sessão com a Etapa do Cartão

Endpoint: POST /v1/sessions
Autenticação: token Bearer com o escopo sessions — veja Autenticação

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": true
    }
  }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ…",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

A resposta é a mesma de qualquer sessão. Entregue o widgetUrl da forma habitual; a etapa do cartão vem depois da selfie.

Para somente verificação, envie apenas capture:

{ "userRef": "user-123", "paymentCard": { "capture": true } }

O Objeto `paymentCard`

Campo	Tipo	Obrigatório	Descrição
`capture`	boolean	Não	`true` adiciona a etapa do cartão a esta sessão. O padrão é `false`
`tokenize`	object	Não	Também tokeniza o cartão pelo tokenizador do gateway. Exige `capture: true`. Envie `{}` para os padrões

`tokenize`

Campo	Tipo	Obrigatório	Descrição
`storeLaterUse`	boolean	Não	`false` (padrão) pede ao gateway um token de uso único, `true` um recorrente. O resultado o informa como `kind`: `one_time` ou `recurring`

O cartão é tokenizado sem 3D Secure, então o titular nunca é desafiado no widget. Autentique quando cobrar o token: veja Tratando o 3D Secure.

Cada objeto aqui recusa um campo que ele não nomeia, então um storeLaterUse com erro de digitação é um 422, e não um token de uso único que você não pediu.

Respostas de Erro

Todas retornam 422 com errorCode: "validation_error", no formato de problema com que todo endpoint de KYC do Inyo360 responde. errors[].field nomeia o campo:

{
  "type": "docs#/components/schemas/ProblemDetails",
  "title": "Unprocessable Entity",
  "status": 422,
  "errorCode": "validation_error",
  "errors": [
    {
      "field": "paymentCard.tokenize",
      "message": "paymentCard.tokenize is not enabled for this tenant",
      "type": "value_error"
    }
  ],
  "correlationId": "…",
  "instance": "/v1/sessions"
}

Causa	`field`	O que fazer
A etapa do cartão não está habilitada para o seu tenant	`paymentCard.capture`	Peça ao seu contato na Inyo para habilitá-la
`tokenize` enviado, e o seu tenant não tem chave de cartão de pagamento	`paymentCard.tokenize`	O tokenizador precisa da chave pública do seu gateway no seu tenant. Peça ao seu contato na Inyo
`tokenize` enviado, e a tokenização está desativada para o seu tenant	`paymentCard.tokenize`	Peça ao seu contato na Inyo, ou envie apenas `capture`
`tokenize` enviado sem `capture: true`	`paymentCard`	Defina `capture: true`. Um cartão só é tokenizado depois de capturado
Um campo que o objeto não nomeia	O campo como enviado	Confira a grafia nas tabelas acima

As recusas que valem para toda a sessão — modo webhook sem webhookUrl, problemas de prefill — estão em Sessões de Verificação.

Configurações que Mudam Depois que um Link é Enviado

A etapa do cartão e a tokenização são lidas novamente sempre que o widget pergunta, não apenas quando a sessão é criada.

O que muda para o seu tenant	Um link já enviado
A tokenização é desativada, ou a chave de cartão de pagamento é removida	A etapa do cartão ainda roda, como somente verificação. Nenhum token é pedido e nenhum bloco `paymentCard` é entregue
A etapa do cartão é desativada	A sessão termina apenas com as etapas de identidade, sem linhas do cartão

Próximos Passos

Fluxo do Widget — o que o titular vê depois da selfie
Resultados — o bloco paymentCard no resultado
Checagens — as linhas do cartão em checks