[EN] - Guia de Implementação

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

  • Adesão

  • Liquidação

  • Diretrizes para essa opção:

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

  • Passo a passo para salvar um id_token

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

  • Tabela de erros “HTTP 400 Bad Request”:

  • Lista de possíveis erros:

  • Diagrama de sequência fluxo CIBA

Option 1: Payment Initiation using an Identification Token (id_token) in the Initiator

The Payment Initiation Service of Open Finance Brazil implements the consent flow with redirection for payment authorization. This redirection can be carried out via redirect between applications or websites <> applications. CIBA provides an alternative for this flow where there's a decoupling of the process and the channel for the authorization can come from a push-notification, SMS, email, WhatsApp, etc.

Adhesion

After a regular redirection, the user, in an account holder with CIBA enabled, can adhere to this form of authorization when accepting consent.

Settlement

In the payment initiator's environment, the user can select the saved account and receive the authorization request via push-notification, SMS, email, WhatsApp, etc. The user must still authorize the consent for the payment to be successfully executed.

Guidelines for this option:

1. Payment initiators and account holders should consider the id_token, obtained in the FAPI Hybrid Flow, as user and account identification to be used at the endpoint to retrieve the payment authentication token.

2. The id_token must have a minimum expiration of 180 days.

3. Payment initiators should display, in the payment flow, the user and account data to be selected. This query can be done by fetching the data from the Payment Consent endpoint (GET /payments/v2/consents/{consentId}, data /data/debtorAccount/number).

4. Use the UX guide as a reference where there will be a checkbox for "save account for future transactions" (UX guide and figma link).

5. The id_token should be used in the authorization call through the "id_token_hint" parameter.

6. Only the "poll mode" will be used to obtain the token for sending the payment via the CIBA Backchannel Authentication Endpoint described in the account holder's well-known.

7. The id_token's cancellation can be carried out by the account holder in fraud cases or for security reasons.

8. The id_token's cancellation can be performed by the payment initiator in cases of fraud or for security reasons, by removing the id_token of the client in its database. Based on FAPI and OIDF protocols, only the removal of the id_token is enough to interrupt the use of the CIBA flow since, after removal, the payment initiator will not be able to reference the client.

Information and validations of an id_token

Information contained in an id_token

Parameters for validating an id_token.

All parameters must be present in the JWT header (header).

Step by step to save an id_token

1. Follow the steps of the Sequence Diagram of a Payment Initiation 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