Autorização FIDO

Authorise Payment Initiation API

Visão Geral

A API de Authorise Payment Initiation permite autorizar um pagamento usando um vínculo (enrollment) autorizado com FIDO (WebAuthn). Este tipo de autorização utiliza autenticação biométrica ou por dispositivo para confirmar a transação.

Características Principais

Uso de Vínculo Autorizado: Requer um enrollment previamente autorizado com FIDO
Autenticação FIDO: Utiliza assertion WebAuthn para autorização
Autorização Final: Após essa etapa, o usuário pode realizar o PIX

Endpoint

POST /open-keys/itp/api/v2/enrollments/v2/payment-initiation/{itp_enrollment_id}/authorise

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_v4_id}",
    "data": {
        "state": "{payment_v4_id}",
        "riskSignals": {
            "deviceId": "12345",
            "isRootedDevice": true,
            "screenBrightness": 0,
            "elapsedTimeSinceBoot": 0,
            "osVersion": "string",
            "userTimeZoneOffset": "-03",
            "language": "pt",
            "screenDimensions": {
                "height": 768,
                "width": 1024
            },
            "accountTenure": "2024-09-13",
            "isCallingProgress": true,
            "isDevModeEnabled": true,
            "isMockGPS": true,
            "isEmulated": true,
            "isMonkeyRunner": true,
            "isCharging": true,
            "antennaInformation": "string",
            "isUsbConnected": true,
            "integrity": {
                "appRecognitionVerdict": "string",
                "deviceRecognitionVerdict": "string"
            }
        },
        "fidoAssertion": {
            "id": "...",
            "rawId": "...",
            "type": "public-key",
            "response": {
                "authenticatorData": "...",
                "clientDataJSON": "...",
                "signature": "...",
                "userHandle": "..."
            }
        }
    }
}

Nota: O campo data enviado nessa requisição é a resposta do assertion no WebAuthn que foi feito depois do fido-sign-options.

Campos da Requisição

Nível Raiz

Campo	Tipo	Obrigatório	Descrição
`paymentInitiationId`	String	Sim	ID do payment initiation criado (PAYMENTS_V4)
`data`	Object	Sim	Objeto contendo os dados da autorização FIDO

Validações Importantes

Enrollment ID: Deve corresponder a um vínculo autorizado com FIDO
Payment Initiation ID: Deve ser um ID válido de payment initiation criado

Implementação

Fluxo de Autorização

A autorização ocorre após:

Criação do payment initiation v4
Obtenção das opções de assinatura FIDO (fido-sign-options)
Geração da assertion WebAuthn
Envio desta requisição de autorização

Resultado: Após a autorização bem-sucedida, o usuário pode realizar o PIX.

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/enrollments/v2/payment-initiation/{itp_enrollment_id}/authorise \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentInitiationId": "{payment_v4_id}",
    "data": {
        "state": "{payment_v4_id}",
        "riskSignals": {
            "deviceId": "12345",
            "isRootedDevice": true,
            "screenBrightness": 0,
            "elapsedTimeSinceBoot": 0,
            "osVersion": "string",
            "userTimeZoneOffset": "-03",
            "language": "pt",
            "screenDimensions": {
                "height": 768,
                "width": 1024
            },
            "accountTenure": "2024-09-13",
            "isCallingProgress": true,
            "isDevModeEnabled": true,
            "isMockGPS": true,
            "isEmulated": true,
            "isMonkeyRunner": true,
            "isCharging": true,
            "antennaInformation": "string",
            "isUsbConnected": true,
            "integrity": {
                "appRecognitionVerdict": "string",
                "deviceRecognitionVerdict": "string"
            }
        },
        "fidoAssertion": {
            "id": "...",
            "rawId": "...",
            "type": "public-key",
            "response": {
                "authenticatorData": "...",
                "clientDataJSON": "...",
                "signature": "...",
                "userHandle": "..."
            }
        }
    }
}'

Resposta da API

Sucesso (200 OK)

A API retorna um objeto confirmando a autorização:

{
    "id": "{payment_v4_id}",
    "paymentInitiationApi": "PAYMENTS_V4",
    "ofConsent": {
        "status": "AUTHORISED"
    }
}

Campos Importantes da Resposta

Campo	Tipo	Descrição
`id`	String	Identificador único do payment initiation
`paymentInitiationApi`	String	Tipo da API (PAYMENTS_V4)
`ofConsent`	Object	Status do consentimento na detentora

Objeto `ofConsent`

Campo	Tipo	Descrição
`status`	String	Status do consentimento (AUTHORISED após autorização)

Erros Comuns

400 Bad Request

{
    "error": "Validation Error",
    "message": "Campo 'fidoAssertion' é obrigatório"
}

Causas comuns:

Campos obrigatórios ausentes
Formato inválido da assertion FIDO
Assertion expirada ou inválida

401 Unauthorized

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

Solução: Verifique se o token de acesso é válido e possui as permissões necessárias (journey ou app).

403 Forbidden

{
    "error": "Forbidden",
    "message": "Enrollment não autorizado ou inválido"
}

Solução: Certifique-se de que o enrollment está autorizado com FIDO.

404 Not Found

{
    "error": "Not Found",
    "message": "Payment Initiation não encontrado"
}

Solução: Verifique se o paymentInitiationId está correto.

Boas Práticas

Validação de Dados: Valide todos os dados antes de enviar a requisição
Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
Segurança: Nunca exponha tokens de acesso no frontend ou logs
FIDO Assertion: Garanta que a assertion seja gerada recentemente e seja válida

Limites e Restrições

Enrollment: Deve estar autorizado com FIDO
Payment Initiation: Deve ser um ID válido de PAYMENTS_V4
FIDO Assertion: Deve ser válida e não expirada
Campos Obrigatórios: Todos os campos marcados como obrigatórios

Notas Adicionais

Após essa autorização bem-sucedida, o usuário poderá realizar o PIX
A assertion FIDO deve ser obtida através do WebAuthn após o fido-sign-options

Updated about 2 hours ago