[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. At the stage of receiving the code, state, id_token on the redirectURL (redirection back from the holder to the initiator), the initiator must save the id_token that also comes in the URL's parameters. Pay attention to item 4 of the sequence diagram link above.

3. Execute the payment as usual because only in the next payment will it be possible to use the CIBA channel to communicate with the client to authorize a consent.

Step by step for a Payment Initiation with the saved id_token

1. Create a phase 3 consent for standard Payment Initiation.

2. Receive a response from the creation of the consent with AWAITING_AUTHORISATION status.

3. Request the CIBA Backchannel Authentication Endpoint for consent authorization, check the payload below:

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&

The fields must be URL-encoded (URL Encoded). In the example, they were left as plain text to facilitate understanding.

The BackchannelAuthenticationEndpoint can be found in the .well-known of the account holder (detentora).

The initiator (iniciadora) must send the consent ID in the scope field along with the openid scope.

The account holder (detentora) must validate the id_token according to the tables referenced above.

Error table “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. Response from the 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: identifier for the authentication request;

expires_in: expiration time of the auth_req_id in seconds, the maximum time the initiator can poll the /token;

interval: minimum polling interval on /token which must be greater than 2 seconds;

5. Upon receiving the call from the Backchannel Authentication Endpoint, the account holder (detentora) should inform the user about the payment request, using the decoupled channel (SMS, push notification, etc) of their choice to authenticate the client according to their policies and authorize the payment.

6. With the payment acknowledged by the user, the account holder (detentora) changes the status of the consent to AUTHORISED.

7. In possession of the auth_req_id, the initiator (iniciadora) must call the /token endpoint at a time interval determined by the interval field from the response of the Backchannel Authentication Endpoint call to receive the access_token, id_token, and the refresh_token of the authorized consent until a time limit determined by the expires_in field of the response. This is the poll mode.

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

The fields must be URL Encoded. In the example, it was left as plaintext to facilitate understanding.

grant_type: should be urn:openid:params:grant-type:ciba

auth_req_id: identifier of the authentication request received in the response from the Backchannel Authentication Endpoint.

8. Conduct polling to get the status of the consent request's authorization. Once the payment request is authorized, the account holder (detentora) should return a successful response with statusCode 200. In cases where the consent has not yet been accepted or has been rejected, the account holder (detentora) should return 403 with the error codes listed below.

Example of a successful response according to 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"
  }

Example of an error response according to CIBA.Core1 10.1.1:

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."
}

List of possible errors:

9. Continue with the payment initiation process and make calls to the payment API, if access is successfully granted.

CIBA flow sequence diagram