Transferências inteligentes (Sweeping Accounts)

Fluxo funcional (da iniciação até o PIX)

1. Criação do pagamento (consentimento)
2. URL de autorização
3. Login na detentora
4. Aprovação do consentimento
5. Callback para o ITP
6. PIX

1. Criação do pagamento (consentimento)

A iniciadora chama a API de payment initiation para registrar o consentimento de sweeping na detentora e obter os dados necessários para o fluxo de autorização.

• Endpoint: POST /open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation
• Autenticação: OAuth2 (app ou journey), header Authorization: Bearer {access_token}

Principais entradas: brandId, redirectUrl, data.loggedUser.document (CPF do pagador), data.creditors[] (contas de destino), data.recurringConfiguration.sweeping (limites totais, por transação e periódicos, startDateTime, opcionalmente expirationDateTime).

A resposta inclui id, authorizationUrl, journeySessionId, ofConsentId e status (inicialmente AWAITING_AUTHORISATION).

2. URL de autorização

A iniciadora utiliza a authorizationUrl retornada na criação do consentimento para redirecionar o usuário ao ambiente da detentora, onde ele irá autenticar e aprovar o consentimento.

Alternativa: criar uma sessão de jornada (POST /open-keys/itp/api/v2/sweeping-accounts/v2/journeys-sessions) e usar a journeySessionUrl para iniciar o fluxo.

3. Login na detentora

O usuário é direcionado à detentora de conta (banco/instituição) e realiza o login no ambiente dela, conforme fluxo da própria detentora.

4. Aprovação do consentimento

Após o login, o usuário visualiza os termos do consentimento de sweeping (limites, credores, vigência) e aprova ou rejeita. A detentora processa essa decisão e, em caso de aprovação, dispara o retorno para o ITP.

5. Callback para o ITP

O ITP recebe a confirmação da aprovação e atualiza o consentimento para AUTHORISED. A aplicação da iniciadora deve consumir o callback com os parâmetros recebidos no redirecionamento para a redirectUrl.

• Endpoint: POST /open-keys/itp/api/v2/payment-initiation/callback
• Payload: code, id_token, state (retornados pela detentora no redirect para a redirectUrl)

Com o callback processado, o consentimento fica autorizado e disponível para uso em transferências PIX automáticas.

6. PIX

Com o consentimento em status AUTHORISED, a iniciadora pode realizar as transferências PIX automáticas (sweeping) dentro dos limites e regras configurados no consentimento (valor por transação, totais e limites periódicos), utilizando os creditors como destino.

Resumo em sequência

Fluxograma

flowchart
    A["Criação do pagamento<br/>Consentimento"] --> B["Retorno da<br/>url de autorização"]
    B --> C["Redirecionar usuário<br/>para url de autorização"]
    C --> D["Login na detentora"]
    D --> E["Aprovação do consentimento<br/>na detentora"]
    E --> F["Redirecionamento para url de autorização<br/>com code, id_token, state"]
    F --> G["Callback para o iniciador"]
    G --> H["Consentimento 'AUTHORISED'"]
    H --> I["Execução de PIX automáticos<br/>Sweeping dentro dos limites"]