Jornada Otimizada (Saldo e Limite)

A Jornada Otimizada permite que o usuário autorize, no mesmo fluxo de um pagamento, o compartilhamento do saldo e do limite da conta pagadora. Antes dela, isso exigia duas jornadas completas e separadas: uma de pagamento e outra de Compartilhamento de Dados.

Com ela, você sabe se há saldo antes de disparar o pagamento. Isso reduz os pagamentos recusados por falta de fundos e dispensa uma segunda jornada de consentimento.

A Jornada Otimizada está disponível para dois produtos:


O que é a Jornada Otimizada

A especificação [JO] Jornada Otimizada v1.0 do Open Finance Brasil segue três princípios:

  • Consentimentos segregados. Ao final existem dois consentimentos: o de pagamento (primário) e o de dados (secundário).
  • APIs existentes. O ecossistema não ganha nenhuma API nova. Valem as APIs de Consentimentos, Recursos e Contas já publicadas.
  • Experiência unificada. O usuário vê uma única jornada de autorização na detentora.
Produto CelcoinConsentimento primárioConsentimento secundário
Jornada Sem Redirecionamento (JSR)Vínculo de dispositivo (enrollment)Dados de saldo e limite (consent)
Transferências Inteligentes (Sweeping Accounts)Consentimento recorrente (recurring-consent)Dados de saldo e limite (consent)
📘

Escopo de dados fechado

O consentimento de dados tem somente as permissões ACCOUNTS_READ, ACCOUNTS_BALANCES_READ, ACCOUNTS_OVERDRAFT_LIMITS_READ e RESOURCES_READ, sobre a mesma conta e com a mesma validade do consentimento de pagamento. Qualquer outra categoria (extrato, cartão, crédito, investimentos) continua exigindo a jornada completa de Recepção de Dados.

O compartilhamento é opcional para o usuário. A opção de compartilhar saldo e limite aparece desmarcada por padrão, e o usuário pode seguir com o pagamento sem aceitá-la.


Como funciona no ecossistema

Você só envia uma flag na chamada de criação. A partir dela, a Celcoin, como iniciadora, executa a sequência definida pela especificação:

  1. Consentimento de dados primeiro. A Celcoin cria o consentimento secundário (POST /consents) com as quatro permissões de saldo e limite e isLinked=true.
  2. Consentimento de pagamento, apontando para o de dados. A Celcoin cria o consentimento primário (POST /enrollments na JSR ou POST /recurring-consents no Sweeping) com o objeto journey, contendo isLinked=true e o linkId igual ao consentId de dados.
  3. Um único redirecionamento. O PAR é enviado com os escopos dos dois consentimentos. A detentora reconhece a Jornada Otimizada por essa combinação de escopos e devolve a URL que chega a você como authorizationUrl.
  4. Aprovação conjunta. O usuário escolhe a conta e a validade uma única vez, e elas valem para os dois consentimentos. Na JSR e no Sweeping, os dois são aprovados juntos ou rejeitados juntos, por isso a escolha de compartilhar é feita na sua tela, e não na detentora.
  5. Um access token com os escopos dos dois consentimentos. O token é renovado enquanto ao menos um dos consentimentos estiver válido. Com os dois expirados ou revogados, a renovação falha com invalid_grant.
🚧

Nem toda detentora oferece a Jornada Otimizada

A detentora precisa ter os papéis de compartilhamento de dados e de detentora de contas, além das APIs de Consentimentos, Recursos e Contas.


📘

Detentora sem suporte

Se você enviar isOptimizedJourney: true para uma marca que não oferece a jornada, a Celcoin segue apenas com o consentimento de pagamento. A jornada e o pagamento funcionam normalmente, e ofDataConsent volta null. Nesse caso, informe ao usuário, na tela de efetivação, que o compartilhamento não foi criado.


Como ativar

Envie "isOptimizedJourney": true no objeto raiz do corpo do POST .../payment-initiation que cria o consentimento de JSR ou de Sweeping. Sem o campo, ou com false, a jornada segue o fluxo convencional, sem consentimento de dados.

CampoTipoObrigatórioDescrição
isOptimizedJourneybooleanNão (padrão false)Com true, cria o consentimento de saldo e limite da conta pagadora junto com o consentimento de pagamento, e os dois são aprovados numa única jornada.
❗️

Só envie true com o aceite do usuário

Envie true somente quando o usuário marcou, na sua tela, a opção de compartilhar saldo e limite. Como a detentora aprova ou rejeita os dois consentimentos juntos, a decisão do usuário precisa estar tomada antes da chamada.

Os exemplos de chamada estão nas páginas de cada produto: JSR e Sweeping Accounts.

A resposta mantém o formato atual de cada produto. Redirecione o usuário para a authorizationUrl: é um único redirecionamento, em que a detentora mostra o pagamento e o compartilhamento de saldo e limite na mesma tela de confirmação. O retorno acontece no redirectUrl informado, como hoje, e o callback continua em POST /baas/v1/open/itp/payment-initiation/callback, com code, id_token e state.


Após a aprovação: consentimento de dados e saldo

Na consulta e no callback, quando isOptimizedJourney foi true, a resposta traz o objeto ofDataConsent:

CampoTipoDescrição
ofDataConsent.consentIdstringURN do consentimento de dados na detentora
ofDataConsent.statusstringAWAITING_AUTHORISATION, AUTHORISED ou REJECTED
ofDataConsent.expirationDateTimestringValidade do consentimento de dados, a mesma do consentimento de pagamento

ofDataConsent vem null quando o compartilhamento não foi criado, por exemplo porque a detentora não oferece a jornada. No Sweeping, o mesmo URN também aparece em ofConsent.journey.linkId, com ofConsent.journey.isLinked: true.

Para consultar o saldo com o URN do consentimento de dados:

  1. Token de dados: POST /baas/v1/open/dat/token, com scope=consent:URN_DE_DADOS openid.
  2. Recursos: GET /baas/v1/open/dat/resources (API Resources - Recursos Consentidos).
  3. Conta: GET /baas/v1/open/dat/accounts, para obter o accountId (API Contas).
  4. Saldo e limite: GET /baas/v1/open/dat/accounts/{accountId}/balances e o endpoint de limites da mesma API Contas.
  5. Pagamento: com saldo suficiente, dispare o Pix pelo fluxo normal: PIX - v4 na JSR ou Execução de Pagamento Pix no Sweeping.

Valem os Limites de Consumo Operacionais dos dados do Open Finance Brasil.


Gestão, revogação e validade

O consentimento de pagamento manda no de dados, nunca o contrário: revogar o pagamento derruba o compartilhamento, mas revogar o compartilhamento mantém o pagamento.

EventoConsentimento de pagamentoConsentimento de dados
Usuário revoga só o compartilhamento de saldo e limiteContinua ativoRevogado
Usuário revoga o vínculo (JSR) ou a autorização (Sweeping)RevogadoRevogado automaticamente
Consentimento de Sweeping chega a CONSUMEDEncerradoRevogado automaticamente
Vínculo JSR tem a validade estendidaEstendidoEstendido para a mesma data
Tentativa de estender só o consentimento de dados—Recusada com HTTP 422 ALTERACAO_NAO_PERMITIDA

Revogar só o compartilhamento. Use o mesmo endpoint que revoga um consentimento de dados avulso, passando o URN do consentimento de dados: DELETE /baas/v1/open/dat/consents/{consent_id}. O consentimento de pagamento continua ativo. Para voltar a ver o saldo, o usuário precisa passar pela jornada completa de Recepção de Dados, porque não há como reativar o consentimento secundário.

Revogar o pagamento. Use o cancelamento já existente de cada produto. O compartilhamento cai junto.

Webhooks: um por consentimento. Cada consentimento notifica as próprias mudanças de status. Uma revogação em cascata gera duas notificações, a do consentimento de pagamento e a do consentimento de dados, e o evento do consentimento de dados traz o paymentInitiationId ao qual está ligado. Trate as duas notificações de forma independente e use o x-celcoin-event-id para deduplicar.

Na área de gestão do seu app, permita revogar o compartilhamento sem cancelar o vínculo ou a autorização, e deixe claro que cancelar o vínculo ou a autorização também encerra o compartilhamento.


Requisitos de experiência

Quem integra via API constrói as telas de solicitação e de efetivação e responde pelos requisitos de iniciadora. A tela de confirmação é da detentora. Os requisitos abaixo são do Guia de Experiência do Usuário v.26.00.00 do Open Finance Brasil.

EtapaO que a tela precisa terJSRSweeping
SolicitaçãoOpção de compartilhar saldo e limite, opcionalREQ.VC-00700REQ.PG-02501
SolicitaçãoOpção desmarcada por padrãoREQ.VC-00800REQ.PG-02502
SolicitaçãoUsuário avança sem ser obrigado a aceitar—REQ.PG-02503
SolicitaçãoAviso de que saldo e limite serão compartilhadosREQ.VC-00900REQ.PG-02504
SolicitaçãoEscopo dos dados compartilhados visívelREQ.VC-01000REQ.PG-02505
SolicitaçãoNada que desvie o foco (links, botões, imagens)REQ.VC-01100REQ.PG-02506
Confirmação (detentora)Aviso de compartilhamento e escopo dos dadosREQ.VC-05600, REQ.VC-05700REQ.PG-05802, REQ.PG-05803
EfetivaçãoInformar que saldo e limite estão sendo compartilhados—REQ.PG-07804
EfetivaçãoInformar que o compartilhamento pode ser cancelado na área de gestãoREQ.VC-07100REQ.PG-07805
EfetivaçãoCancelar o compartilhamento não cancela o vínculoREQ.VC-07200—
EfetivaçãoCancelar o vínculo também cancela o compartilhamentoREQ.VC-07300—

Casos de erro

Além dos erros já documentados de cada produto (400, 401, 403, 404, 422), a Jornada Otimizada tem situações próprias:

SituaçãoOnde ocorreO que fazerRequisito
Pagamento autorizado, mas o compartilhamento de saldo e limite falhouEfetivação, no seu appInformar o usuário. O vínculo ou a autorização continuam válidos. Ex.: "Falha no compartilhamento de saldo e limite. O vínculo com a [Instituição] foi criado, mas o compartilhamento falhou."REQ.VC-10600 / REQ.PG-10704
Falha ao cancelar o compartilhamentoGestão, no seu app ou na detentoraInformar e oferecer nova tentativaREQ.VC-10800 / REQ.PG-11003
Tentativa de estender a validade só do consentimento de dadosAPI da detentoraHTTP 422 ALTERACAO_NAO_PERMITIDA. Estender pelo consentimento primário (JSR)Especificação [JO]
Permissões além de saldo e limite no consentimento vinculadoAPI da detentoraHTTP 422 COMBINACAO_PERMISSOES_INCORRETA. A Celcoin monta as permissões, então isso não deve ocorrer na integraçãoEspecificação [JO]
Renovação do token com os dois consentimentos inválidosServidor de autorizaçãoinvalid_grant. É necessária uma nova jornadaEspecificação [JO]
Detentora sem suporteCriaçãoA jornada segue só com o pagamento e ofDataConsent vem null. Informar o usuário como no primeiro caso desta tabelaREQ.VC-10600 / REQ.PG-10704

Referências


Did this page help you?