FIDO Sign Options API

Visão Geral

A API de FIDO Sign Options permite obter as opções de assinatura FIDO (WebAuthn) para um pagamento usando um vínculo (enrollment) autorizado. A resposta contém os dados necessários para gerar uma assertion no WebAuthn, incluindo challenge, credenciais permitidas e configurações de autenticação.

Características Principais

• Uso de Vínculo Autorizado: Requer um enrollment previamente autorizado com FIDO
• Geração de Assertion: A resposta deve ser usada para gerar uma assertion WebAuthn para autenticação do pagamento

Endpoint

POST /open-keys/itp/api/v2/enrollments/v2/payment-initiation/{itp_enrollment_id}/fido-sign-options

Nota: O {itp_enrollment_id} nesta requisição é o ID retornado na criação do vínculo de dispositivo.

Autenticação

A API requer autenticação OAuth2 com uma das seguintes permissões:

• journey: Para fluxos que utilizam redirecionamento à detentora de conta
• app: Para integrações diretas via API

O token de acesso deve ser enviado no header:

Authorization: Bearer {access_token}

Estrutura da Requisição

Payload Completo

{
    "paymentInitiationId": "{payment_initiation_v4_id}",
    "data": {
        "rp": "{fido_rp}",
        "platform": "{fido_platform}"
    }
}

Campos da Requisição

Nível Raiz

Objeto data

Validações Importantes

1. Enrollment ID: Deve corresponder a um vínculo autorizado
2. Payment Initiation ID: Deve ser um ID válido de payment initiation criado
3. Campos Obrigatórios: paymentInitiationId, rp e platform são obrigatórios

Implementação

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/enrollments/v2/payment-initiation/{itp_enrollment_id}/fido-sign-options \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentInitiationId": "{payment_v4_id}",
    "data": {
        "rp": "{fido_rp}",
        "platform": "{fido_platform}"
    }
}'

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo as opções de assinatura FIDO:

{
    "challenge": "...",
    "allowCredentials": [
        {
            "id": "...",
            "type": "public-key"
        }
    ],
    "timeout": 60000,
    "userVerification": "preferred",
    "rpId": "localhost:8000"
}

Nota: Esta resposta deve ser usada diretamente para gerar uma assertion no WebAuthn.

Erros Comuns

401 Unauthorized

{
    "error": "Unauthorized",
    "message": "Token inválido ou expirado"
}

Solução: Verifique se o token de acesso é válido.

404 Not Found

{
    "error": "Not Found",
    "message": "Enrollment não encontrado ou Payment Initiation inválido"
}

Solução: Verifique se o itp_enrollment_id e paymentInitiationId estão corretos.

400 Bad Request

{
    "error": "Bad Request",
    "message": "Campos obrigatórios ausentes"
}

Causas comuns:

• Campos paymentInitiationId, rp ou platform ausentes
• Formato inválido dos dados

Boas Práticas

1. Validação de Dados: Valide todos os dados antes de enviar a requisição
2. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
3. Segurança: Nunca exponha tokens de acesso no frontend ou logs

Limites e Restrições

• Enrollment: Deve estar autorizado com FIDO
• Payment Initiation: Deve ser um ID válido de PAYMENTS_V4

Notas Adicionais

• A resposta desta API deve ser usada para gerar uma assertion WebAuthn, que será enviada na autorização do pagamento