[PT] - Guia de Implementação

Opção 1: Iniciação de pagamento usando um Token de Identificação (id_token) na Iniciadora

O serviço de Iniciação de Pagamentos do Open Finance Brasil implementa o fluxo de consentimento com redirecionamento para a autorização de pagamentos. Esse redirecionamento pode ser realizado via redirect entre aplicativos ou sites <> aplicativos. O CIBA fornece uma alternativa para esse fluxo onde ocorre um desacoplamento do processo e o canal para a autorização poderá ser um push-notification, SMS, email, WhatsApp etc.

Adesão

Após um redirecionamento comum, o usuário, em um detentor de conta com CIBA habilitado, poderá aderir a essa forma de autorização no aceite de um consentimento.

Liquidação

No ambiente do iniciador de pagamentos o usuário poderá selecionar a conta salva e receber o pedido de autorização via push-notification, SMS, email, WhatsApp etc. O usuário ainda deverá autorizar o consentimento para que o pagamento seja efetuado com sucesso.

Diretrizes para essa opção:

1. Iniciadores de pagamento e detentores de conta devem considerar o id_token, obtido no fluxo de FAPI Hybrid Flow como identificação de usuário e conta a ser utilizado em endpoint para recuperar token de autenticação do pagamento;

2. O id_token deverá ter no mínimo 180 dias de expiração;

3. Os iniciadores de pagamento deverão mostrar no fluxo de pagamento os dados do usuário e conta para ser selecionado, essa consulta poderá ser feita buscando os dados do endpoint de Consentimento de Pagamentos (GET /payments/v2/consents/{consentId}, dado /data/debtorAccount/number);

4. Utilizar como base de experiência o guia de UX onde existirá um checkbox para “salvar conta para transações futuras” (link do guia de UX e figma);

5. O id_token deve ser utilizado na chamada de autorização através do parâmetro “id_token_hint”;

6. Apenas o “poll mode” será utilizado para obter token para o envio do pagamento via endpoint Backchannel Authentication Endpoint do CIBA descrito no well-known da Detentora de Contas;

7. O cancelamento do id_token poderá ser realizado pela detentora de conta em casos de fraude ou por motivos de segurança;

8. O cancelamento do id_token poderá ser realizado pela iniciadora de pagamentos em caso de fraude ou por motivos de segurança, através da remoção do id_token do cliente em sua base de dados. Com base nos protocolos FAPI e OIDF, apenas a remoção do id_token é suficiente para interromper o uso do fluxo CIBA, uma vez que, após a remoção, a iniciadora de pagamentos não será capaz de referenciar o cliente.

Informações e validações de um id_token

Informação contidas em uma id_token

Parâmetros para validação de um id_token

Todos os parâmetros devem estar presentes no cabeçalho (header) do JWT.

Passo a passo para salvar um id_token

1. Siga os passos do Diagrama de Sequência de uma Iniciação de Pagamento via Hybrid-Flow;

2. Na etapa de recebimento do code, state, id_token no redirectURL (redirecionamento de volta da detentora para a iniciadora) a iniciadora deve salvar o id_token que também vem nos parâmetros da url de redirect. Atentar-se ao item 4 do diagrama de sequência do link acima;

3. Realizar o pagamento normalmente, pois apenas no próximo pagamento será possível a utilização do canal CIBA para a comunicação com o cliente para autorizar um consentimento.

Passo a passo de uma Iniciação de Pagamento com o id_token salvo

1. Criar um consentimento fase 3 para Iniciação de Pagamentos padrão;

2. Receber resposta da criação do consentimento com status AWAITING_AUTHORISATION;

3. Requisitar Backchannel Authentication Endpoint do CIBA para autorização do consentimento, verificar payload abaixo:

POST {BackchannelAuthenticationEndpoint} HTTP/1.1
Host: {AuthorizationServer}
Content-Type: application/x-www-form-urlencoded

scope=openid consent:urn:bancoex:C1DD33123&
id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2Nzcy
NiJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSI
sInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDM
iLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE
  1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFV
  JLjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJ
  XNKWAg_dxVynvMHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8icz
  D16A5gNjSD7yenT5fslrrW-NU_vtmi0s1puoM4EmSaPXCR19vRJy
  WuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LHfW1G74NY5DaPv-V
  23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1EFW
  tjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7
  MtVb2UlCwDQrVlg&

Os campos devem ser codificados para url (URL Encoded). No exemplo foi deixado como plain text para facilitar o entendimento.

O BackchannelAuthenticationEndpoint deve ser encontrado no .well-known da detentora.

A iniciadora deve enviar o id do consentimento no campo scope junto com o scope openid.

A detentora deverá validar o id_token de acordo com as tabelas referenciadas acima dos itens.

Tabela de erros “HTTP 400 Bad Request”:

1. invalid_request: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, contains more than one of the hints, or is otherwise malformed.

2. invalid_scope: The requested scope is invalid, unknown, or malformed.

3. expired_id_token_hint: The id_token hint provided in the authentication request is not valid because it has expired.

4. unknown_user_id: The OpenID Provider is not able to identify which end-user the Client wishes to be authenticated by means of the hint provided in the request (id_token_hint).

5. unauthorized_client: The Client is not authorized to use this authentication flow.

6. invalid_id_token_hint: The id_token is invalid and can’t be used in the flow.

4. Resposta do Backchannel Authentication Endpoint:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
  "expires_in": 120,
  "interval": 2
}

auth_req_id: identificador da requisição de autenticação;

expires_in: tempo de expiração do auth_req_id em segundos, tempo máximo que a iniciadora poderá fazer o polling do /token;

interval: intervalo mínimo do polling no /token que deve ser maior que 2 segundo;

5. Ao receber a chamada do Backchannel Authentication Endpoint, a detentora deve informar o usuário sobre a solicitação de pagamento, utilizando o canal desacoplado (SMS, push notification, etc) de sua escolha para autenticar o cliente de acordo com suas políticas e autorizar o pagamento.

6. Com o pagamento reconhecido pelo usuário a detentora muda o status do consentimento para AUTHORISED.

7. Em posse do auth_req_id a iniciadora deve chamar o endpoint /token em um intervalo de tempo determinado pelo campo interval da resposta da chamada do Backchannel Authentication Endpoint para receber o access_token , id_token e o refresh_token do consentimento autorizado até um tempo limite determinado pelo campo expires_in da resposta. Esse é o modo poll.

POST {TokenEndpoint} HTTP/1.1
Host: {AuthorizationServer}

Content-Type: application/x-www-form-urlencoded
grant_type=urn:openid:params:grant-type:ciba&   //    Mandatory
auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1    //    Mandatory

Os campos devem ser codificado para url (URL Encoded). No exemplo foi deixado como plaintext para facilitar o entendimento.

grant_type: deve ser urn:openid:params:grant-type:ciba

auth_req_id: identificador da requisição de autenticação recebido na resposta da chamada do Backchannel Authentication Endpoint.

8. Realizar polling para obter o status da autorização da solicitação de consentimento, uma vez autorizada a solicitação de pagamento a detentora deve retornar uma resposta de sucesso com statusCode 200. Para os casos onde o consentimento ainda não foi aceito ou foi rejeitado a detentora deverá retornar 403 com os error codes listados abaixo.

Exemplo de resposta de sucesso conforme CIBA.Core1 10.1.1:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":   "9f312798-11e7-4e87-a143-b83bd1c2026f",
  "token_type":     "Bearer",
  "refresh_token":  "c410670a-5cb9-4bef-aa0d-d5c30e3d33a3",
  "expires_in":     120,
  "id_token":       "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2Nzcy
      NiJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSI
      sInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDM
      iLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE
      1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFV
      JLjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJ
      XNKWAg_dxVynvMHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8icz
      D16A5gNjSD7yenT5fslrrW-NU_vtmi0s1puoM4EmSaPXCR19vRJy
      WuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LHfW1G74NY5DaPv-V
      23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1EFW
      tjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7
      MtVb2UlCwDQrVlg"
  }

Exemplo de resposta de erro conforme CIBA.Core1 11:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
    1. "error": "authorization_pending",
    2. "error_description": "The user has not yet been authenticated, and the authorization request is still pending."
}

Lista de possíveis erros:

9. Seguir com o processo de uma iniciação de pagamento e realizar as chamadas na API de pagamento, caso o acesso for concedido com sucesso.

Diagrama de sequência fluxo CIBA