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 Celcoin | Consentimento primário | Consentimento 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 fechadoO consentimento de dados tem somente as permissões
ACCOUNTS_READ,ACCOUNTS_BALANCES_READ,ACCOUNTS_OVERDRAFT_LIMITS_READeRESOURCES_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:
- Consentimento de dados primeiro. A Celcoin cria o consentimento secundário (
POST /consents) com as quatro permissões de saldo e limite eisLinked=true. - Consentimento de pagamento, apontando para o de dados. A Celcoin cria o consentimento primário (
POST /enrollmentsna JSR ouPOST /recurring-consentsno Sweeping) com o objetojourney, contendoisLinked=truee olinkIdigual aoconsentIdde dados. - 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. - 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.
- 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 OtimizadaA 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 suporteSe você enviar
isOptimizedJourney: truepara uma marca que não oferece a jornada, a Celcoin segue apenas com o consentimento de pagamento. A jornada e o pagamento funcionam normalmente, eofDataConsentvoltanull. 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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
isOptimizedJourney | boolean | Nã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ó envietruecom o aceite do usuárioEnvie
truesomente 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:
| Campo | Tipo | Descrição |
|---|---|---|
ofDataConsent.consentId | string | URN do consentimento de dados na detentora |
ofDataConsent.status | string | AWAITING_AUTHORISATION, AUTHORISED ou REJECTED |
ofDataConsent.expirationDateTime | string | Validade 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:
- Token de dados:
POST /baas/v1/open/dat/token, comscope=consent:URN_DE_DADOS openid. - Recursos:
GET /baas/v1/open/dat/resources(API Resources - Recursos Consentidos). - Conta:
GET /baas/v1/open/dat/accounts, para obter oaccountId(API Contas). - Saldo e limite:
GET /baas/v1/open/dat/accounts/{accountId}/balancese o endpoint de limites da mesma API Contas. - 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.
| Evento | Consentimento de pagamento | Consentimento de dados |
|---|---|---|
| Usuário revoga só o compartilhamento de saldo e limite | Continua ativo | Revogado |
| Usuário revoga o vínculo (JSR) ou a autorização (Sweeping) | Revogado | Revogado automaticamente |
Consentimento de Sweeping chega a CONSUMED | Encerrado | Revogado automaticamente |
| Vínculo JSR tem a validade estendida | Estendido | Estendido 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.
| Etapa | O que a tela precisa ter | JSR | Sweeping |
|---|---|---|---|
| Solicitação | Opção de compartilhar saldo e limite, opcional | REQ.VC-00700 | REQ.PG-02501 |
| Solicitação | Opção desmarcada por padrão | REQ.VC-00800 | REQ.PG-02502 |
| Solicitação | Usuário avança sem ser obrigado a aceitar | — | REQ.PG-02503 |
| Solicitação | Aviso de que saldo e limite serão compartilhados | REQ.VC-00900 | REQ.PG-02504 |
| Solicitação | Escopo dos dados compartilhados visível | REQ.VC-01000 | REQ.PG-02505 |
| Solicitação | Nada que desvie o foco (links, botões, imagens) | REQ.VC-01100 | REQ.PG-02506 |
| Confirmação (detentora) | Aviso de compartilhamento e escopo dos dados | REQ.VC-05600, REQ.VC-05700 | REQ.PG-05802, REQ.PG-05803 |
| Efetivação | Informar que saldo e limite estão sendo compartilhados | — | REQ.PG-07804 |
| Efetivação | Informar que o compartilhamento pode ser cancelado na área de gestão | REQ.VC-07100 | REQ.PG-07805 |
| Efetivação | Cancelar o compartilhamento não cancela o vínculo | REQ.VC-07200 | — |
| Efetivação | Cancelar o vínculo também cancela o compartilhamento | REQ.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ção | Onde ocorre | O que fazer | Requisito |
|---|---|---|---|
| Pagamento autorizado, mas o compartilhamento de saldo e limite falhou | Efetivação, no seu app | Informar 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 compartilhamento | Gestão, no seu app ou na detentora | Informar e oferecer nova tentativa | REQ.VC-10800 / REQ.PG-11003 |
| Tentativa de estender a validade só do consentimento de dados | API da detentora | HTTP 422 ALTERACAO_NAO_PERMITIDA. Estender pelo consentimento primário (JSR) | Especificação [JO] |
| Permissões além de saldo e limite no consentimento vinculado | API da detentora | HTTP 422 COMBINACAO_PERMISSOES_INCORRETA. A Celcoin monta as permissões, então isso não deve ocorrer na integração | Especificação [JO] |
| Renovação do token com os dois consentimentos inválidos | Servidor de autorização | invalid_grant. É necessária uma nova jornada | Especificação [JO] |
| Detentora sem suporte | Criação | A jornada segue só com o pagamento e ofDataConsent vem null. Informar o usuário como no primeiro caso desta tabela | REQ.VC-10600 / REQ.PG-10704 |
Referências
Updated about 7 hours ago