Enrollment V2 - Payment Initiation API

Visão Geral

A API de Enrollment V2 permite a criação de consentimentos para vínculos de pagamento recorrentes (enrollments). Este tipo de consentimento permite que uma instituição iniciadora de pagamento estabeleça um vínculo autorizado com o usuário pagador, utilizando autenticação FIDO (WebAuthn) para autorizações futuras de pagamentos sem necessidade de reautenticação a cada transação.

Características Principais

• Vínculo Recorrente: Permite múltiplas autorizações de pagamento usando o mesmo vínculo estabelecido
• Autenticação FIDO: Utiliza WebAuthn para registro e autenticação segura do dispositivo
• Controle de Permissões: Define permissões específicas para o vínculo (ex: PAYMENTS_INITIATE)
• Sinais de Risco: Coleta informações de risco do dispositivo para avaliação de segurança
• Fluxo de Jornada: Suporta redirecionamento para autorização na detentora de conta

Endpoint

POST /open-keys/itp/api/v2/enrollments/v2/payment-initiation

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

{
    "brandId": "{enrollment_brand_id}",
    "redirectUrl": "{redirect_url}",
    "data": {
        "enrollment": {
            "loggedUser": {
                "document": {
                    "identification": "{enrollment_cpf}",
                    "rel": "CPF"
                }
            },
            "permissions": ["PAYMENTS_INITIATE"]
        },
        "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"
            }
        }
    }
}

Campos da Requisição

Nível Raiz

Objeto data

Objeto enrollment

Objeto loggedUser

Objeto document

Objeto riskSignals

Contém informações de risco coletadas do dispositivo do usuário para avaliação de segurança.

Formato de Valores

Os campos de identificação seguem padrões específicos:

• Datas: Formato ISO 8601 (ex: "2024-09-13")

Validações Importantes

1. Document: Deve conter CPF válido com 11 dígitos
2. Permissions: Deve incluir ao menos uma permissão válida
3. Redirect URL: Deve estar cadastrada e autorizada para a aplicação
4. Brand ID: Deve existir no sistema
5. Risk Signals: Todos os campos obrigatórios devem ser fornecidos

Implementação

Fluxo de Criação de Enrollment

A criação de enrollment pode ocorrer de duas formas, dependendo do escopo de autenticação:

1. Fluxo com journey (Redirecionamento)

Quando o token possui o escopo journey:

1. O sistema cria uma sessão de jornada (journey-session)
2. Cria o registro de payment initiation
3. Cria o enrollment na detentora de conta
4. Retorna a URL de autorização para redirecionamento

Uso: Quando o usuário precisa ser redirecionado para autorizar o enrollment na detentora de conta.

2. Fluxo com app (API Direta)

Quando o token possui o escopo app:

1. O sistema valida o redirectUrl da aplicação
2. Cria uma sessão de jornada automaticamente
3. Cria o registro de payment initiation
4. Cria o enrollment na detentora de conta
5. Retorna a URL de autorização

Uso: Para integrações diretas via API sem necessidade de redirecionamento imediato.

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/enrollments/v2/payment-initiation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "directoryCallback": false,
    "data": {
        "enrollment": {
            "loggedUser": {
                "document": {
                    "identification": "12345678901",
                    "rel": "CPF"
                }
            },
            "permissions": ["PAYMENTS_INITIATE"]
        },
        "riskSignals": {
            "deviceId": "12345",
            "isRootedDevice": false,
            "screenBrightness": 50,
            "elapsedTimeSinceBoot": 3600000,
            "osVersion": "Android 12",
            "userTimeZoneOffset": "-03",
            "language": "pt",
            "screenDimensions": {
                "height": 1920,
                "width": 1084
            },
            "accountTenure": "2024-09-13",
            "isCallingProgress": false,
            "isDevModeEnabled": false,
            "isMockGPS": false,
            "isEmulated": false,
            "isMonkeyRunner": false,
            "isCharging": false,
            "antennaInformation": "LTE",
            "isUsbConnected": false,
            "integrity": {
                "appRecognitionVerdict": "TRUSTED",
                "deviceRecognitionVerdict": "TRUSTED"
            }
        }
    }
}'

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo:

{
    "id": "{itp_enrollment_id}",
    "paymentInitiationApi": "ENROLLMENTS_V2",
    "journeySessionId": "...",
    "authorizationUrl": "...",
    "ofEnrollmentId": "...",
    "..."
}

Campos Importantes da Resposta

Erros Comuns

400 Bad Request

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

Causas comuns:

• Campos obrigatórios ausentes
• Formato de dados inválido (CPF, datas)
• Validação de schema falhou

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": "this redirectUrl is not allowed for this application"
}

Solução: Certifique-se de que o redirectUrl está cadastrado e autorizado para a aplicação.

404 Not Found

{
    "error": "Not Found",
    "message": "Brand não encontrada"
}

Solução: Verifique se o brandId informado existe no sistema.

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
4. URLs de Redirecionamento: Use HTTPS em produção para redirectUrl
5. Sinais de Risco: Colete sinais de risco reais do dispositivo para melhor avaliação de segurança

Limites e Restrições

• Redirect URL: Deve estar autorizada para a aplicação
• Risk Signals: Todos os campos obrigatórios devem ser fornecidos com valores realistas

Notas Adicionais

• O enrollment criado precisa ser autorizado pelo usuário na detentora de conta através da authorizationUrl retornada
• Após a autorização, o status do enrollment será atualizado
• O enrollment permite o uso de FIDO para autorizações futuras de pagamentos