Page Comparison

Table of Contents

maxLevel	2

...

The sequence diagram below highlights the OAuth 2.0 Client Credentials Grant and OIDC Hybrid flow that are used by the Payments API.

Image RemovedImage Added

Code Block

title	Payment Initiation with Client Credentials Grant Type and OIDC Hybrid Flows
collapse	true

participant PSU
participant PISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
   
autonumber 1
    
PSU -> PISP: Establish TLS 1.2
    
note over PSU, ASPSP Resource Server
Step 1: Request payment initiation
end note
PSU -> PISP: Send payment initiation request
     
note over PSU, ASPSP Resource Server
 Step 2: Setup single payment initiation
end note
    
    PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
    note left of PISP
        Client Credentials Grant
    end note
    PISP->ASPSP Authorisation Server: POST /token (client authentication credentials, scope:payments)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials, scope
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server -> PISP: HTTP 200 (OK) access-token (scope:payments)
        
    
    PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    PISP -> ASPSP Resource Server: POST /payments (access-token - scope:payments)
    ASPSP Resource Server->ASPSP Resource Server: Validate access token
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:payments
    ASPSP Resource Server->ASPSP Resource Server: Validate clientId matches client SSL cert
       
    ASPSP Resource Server->ASPSP Resource Server: Create new payment resource
    ASPSP Resource Server->ASPSP Resource Server: Bind PaymentId with ClientId
    ASPSP Resource Server -> PISP: HTTP 201 (Created),  PaymentId
    
    note right of PISP
        Begin OIDC Hybrid Flow.
        See 6.1.  Passing a Request Object by Value
        See 5.5.  Requesting Claims using the "claims" Request Parameter
        The claims parameter must at least request:
             "id_token": {
       "openbanking_intent_id": {"value": PaymentId, "essential": true},
       "acr": {"essential": true}
      }
      The response object must be signed using the PISP's private key.
    end note
    PISP->PISP: Persist PaymentId
    note right of PISP
        The PISP should store the PaymentId in a manner
        that it can be retrieved again later in the flow in Step 4.
           
        This could be stored in the user session (and retrieved using 'state'
        as a key) or the PSU could use some other unique identifier.
           
        This will be re-retrieved in [43].
           
    end note
    PISP->PISP: Create signed request object with requested Claims (PaymentId)
    PISP -> PSU: HTTP 302 (Found); Location: /authorize,\nredirect-uri, clientId, state, nonce, scope=openid payments,\nresponse-type=code id_token,\nrequest=signed JWT request object - PaymentId)
    
note over PSU, ASPSP Resource Server
 Step 3: Authorize consent
end note
    
PSU -> ASPSP Authorisation Server: HTTP GET /authorize redirect-uri, clientId, state, nonce, scope=openid payments, response-type=code id_token,\nrequest=signed JWT request object - PaymentId
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientid, scope
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate redirect-uri for clientId
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate JWT request claim -PaymentId
    note right of ASPSP Authorisation Server
        Validate the request object by using the PISP's public key.
        PISP certificate will be identified using the kid claim
        in the JOSE header of the request object.
           
        Check that the PaymentId belongs to the ClientId that initiated the request.
    end note
ASPSP Authorisation Server<->PSU: Authenticate (Login and consent page)
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: Select debtor account
ASPSP Authorisation Server->ASPSP Authorisation Server: Generate authorization-code, id_token
note right of ASPSP Authorisation Server
    id_token claims:{
    c_hash: 123,
    s_hash: 456
    }
    id_token must be signed using the ASPSP's private key.
    The generation of c_hash is documented in OIDC: 3.3.2.11.  ID Token
    The generation of s_hash is in FAPI R/W spec: Section 5.1
    http://openid.net/specs/openid-financial-api-part-2-wd-02.html#introduction
end note
   
ASPSP Authorisation Server -> PSU: HTTP 302 (Found); Location: redirect-uri (authorization-code, id_token, state)
PSU -> PISP: HTTP GET redirect-uri (authorization-code, id_token, state)
PISP->PISP: Validate signature on id_token
note right of PISP
    Validate the id_token by using the ASPSP's public key.
    ASPSP certificate will be identified using the kid claim
    in the JOSE header of the id_token
end note
PISP->PISP: Validate authorization-code using id_token (c_hash)
PISP->PISP: Validate state using id_token (s_hash)
PISP->PISP: Validate nonce using id_token
    
    
note right of PISP:
    Exchange authorization-code for access token.
end note
PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
PISP -> ASPSP Authorisation Server: HTTP POST /token (client authentication credentials,\nauthorization-code, grant_type, redirect_uri)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials,\nauthorization-code
    ASPSP Authorisation Server->ASPSP Authorisation Server: Generate access-token
    ASPSP Authorisation Server->ASPSP Authorisation Server: Bind access-token to PaymentId
       
ASPSP Authorisation Server -> ASPSP Resource Server: Update Payment Status to AcceptedCustomerProfile
ASPSP Resource Server -> ASPSP Authorisation Server: OK
note right of ASPSP Authorisation Server
    Implementation of how the resource is updated is ASPSP specific. (There is
    no standardised API for this)
end note
   
   
ASPSP Authorisation Server -> PISP: HTTP 200 (OK) access-token (scope:payments)
     
       
note over PSU, ASPSP Resource Server
Step 4: Create payment submission
end note
PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
PISP->PISP: Retrieve PaymentId
note left of PISP
    Retrieve the PaymentId that was issued in Step 2.
    The method for doing this will depend on how the PISP persisted
    the payment id in [16]
       
end note
   
alt Validate PaymentId in  ID Token
    PISP->PISP: Decode / verify ID Token
    PISP->PISP: Read PaymentId from id_token claim
    PISP->PISP: Compare with PaymentId retrieved in [43]
else Validate PaymentId from UserInfo endpoint
    PISP->ASPSP Resource Server: GET /userInfo (access-token)
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->PISP: HTTP 200 (OK) - UserInfo claim - PaymentId
end
PISP -> ASPSP Resource Server: POST /payment-submissions (access-token - scope:payments) using PaymentId
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:payments
    note right of ASPSP Resource Server
        Check binding created in [38]
    end note
    ASPSP Resource Server->ASPSP Resource Server: Ensure access-token is bound to PaymentId
    ASPSP Resource Server->ASPSP Resource Server: Update payment status to AcceptedSettlementInProcess
ASPSP Resource Server -> PISP: HTTP 201 (Created), PaymentSubmissionId
     
note over PSU, ASPSP Resource Server
Step 5: Get payment submission status
end note
     
opt
    PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    alt Use active access token to retrieve payment status
        PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId} (access-token - scope:payments)
        ASPSP Resource Server->ASPSP Resource Server: Validate access-token
        ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
        ASPSP Resource Server->ASPSP Resource Server: Validate scope:payments
        ASPSP Resource Server->PISP: HTTP 200 (OK), payment-submissions resource
    else Initiate fresh access token via client credentials grant
        note left of PISP
            Client Credentials Grant
        end note
        PISP->ASPSP Authorisation Server: POST /token (client authentication credentials, scope:payments)
        ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials, scope
        ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
        ASPSP Authorisation Server -> PISP: HTTP 200 (OK) access-token (scope:payments)
        PISP -> ASPSP Resource Server: GET /payment-submissions/{PaymentSubmissionId} (access-token - scope:payments)
        ASPSP Resource Server->ASPSP Resource Server: Validate access-token
        ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
        ASPSP Resource Server->ASPSP Resource Server: Validate scope:payments
        ASPSP Resource Server->PISP: HTTP 200 (OK), payment-submissions resource
    end alt
end opt

...

1. The PISP can query for the status of a Payment-Submission by invoking the /payment-submissions using the known PaymentSubmissionId. This can use an existing access token with payments scope or the PISP can obtain a fresh access token by replaying the client credentials grant request as per Step 2 - Setup Single Payment Initiation.

Request: payment-submissions/{PaymentSubmissionId}

Response: payment-submissions

Code Block

theme	Midnight

GET /payment-submissions/58923-001 HTTP/1.1
Authorization: Bearer SlAV32hkKG
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: 2017-06-13T11:36:09
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Code Block

theme	Midnight

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "PaymentSubmissionId": "58923-001",
    "PaymentId": "58923",
    "Status": "AcceptedSettlementInProcess",
    "CreationDateTime": "2017-06-05T15:15:22+00:00"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v1.0/payment-submissions/58923-001"
  },
  "Meta": {}
}

2. A PISP can also optionally query for the status of a Payment resource by invoking /payments/{PaymentId}. This can use an existing access token with payments scope or the PISP can obtain a fresh access token by replaying the client credentials grant request as per Step 2 - Setup Single Payment Initiation.

Account API Specification

The sequence diagram below highlights the OAuth 2.0 Client Credentials Grant and OIDC Hybrid flow that are used by the Account and Transactions API.

Image RemovedImage Added

Code Block

title	Account and Transactions API with Client Credentials Grant and OIDC Hybrid flow
collapse	true

 participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
autonumber 1
      
PSU -> AISP: Establish TLS 1.2
    
      
note over PSU, ASPSP Resource Server
    Step 1: Request account information
end note
PSU -> AISP: Get account/transaction information
     
note over PSU, ASPSP Resource Server
    Step 2: Setup account request
end note
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
    
    note left of AISP
        Client Credentials Grant
    end note
    AISP->ASPSP Authorisation Server: POST /token (client authentication credentials, scope:accounts)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials, scope
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token (scope:accounts)
    
    
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: POST /account-requests (access-token - scope:accounts)
    ASPSP Resource Server->ASPSP Resource Server: Validate access token
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
    ASPSP Resource Server->ASPSP Resource Server: Validate clientId matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Create new account resource
    ASPSP Resource Server->ASPSP Resource Server: Bind AccountRequestId with ClientId
    
ASPSP Resource Server -> AISP: HTTP 201 (Created), AccountRequestId
    note right of AISP
        Begin OIDC Hybrid Flow.
        See 6.1.  Passing a Request Object by Value
        See 5.5.  Requesting Claims using the "claims" Request Parameter
        The claims parameter must at least request:
             "id_token": {
       "openbanking_intent_id": {"value": AccountRequestId, "essential": true},
       "acr": {"essential": true}
      }
      The response object must be signed using the PISP's private key.
    end note
    AISP->AISP: Persist AccountRequestId
      note right of AISP
        The AISP should store the AccountRequestId in a manner
        that it can be retrieved again later in the flow in Step 4.
             
        This could be stored in the user session (and retrieved using 'state'
        as a key) or the PSU could use some other unique identifier.
             
        This can be re-retrieved in [81] and [96].
             
    end note
    
    AISP->AISP: Create signed request object with requested Claims (AccountRequestId)
        
    
    
    AISP -> PSU: HTTP 302 (Found); Location: /authorize,\nredirect-uri, clientId, state, nonce, scope=openid accounts,\nresponse-type=code id_token,\nrequest=signed JWT request object - AccountRequestId)
    
     
note over PSU, ASPSP Resource Server
Step 3: Authorise consent
end note
PSU -> ASPSP Authorisation Server: HTTP GET /authorize redirect-uri, clientId, state, nonce, scope=openid accounts, response-type=code id_token,\nrequest=signed JWT request object - AccountRequestId
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientid, scope
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate redirect-uri for clientId
ASPSP Authorisation Server->ASPSP Authorisation Server: Validate JWT request claim -AccountRequestId
note right of ASPSP Authorisation Server
        Validate the request object by using the PISP's public key.
        PISP certificate will be identified using the kid claim
        in the JOSE header of the request object.
             
        Check that the AccountRequestId belongs to the ClientId that initiated the request.
    end note
    
PSU <-> ASPSP Authorisation Server: Authenticate (Login and Consent Page)
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: Select Accounts
ASPSP Authorisation Server->ASPSP Authorisation Server: Generate authorization-code, id_token
note right of ASPSP Authorisation Server
    id_token claims:{
    c_hash: 123,
    s_hash: 456
    }
    id_token must be signed using the ASPSP's private key.
    The generation of c_hash is documented in OIDC: 3.3.2.11.  ID Token
    The generation of s_hash is in FAPI R/W spec: Section 5.1
    http://openid.net/specs/openid-financial-api-part-2-wd-02.html#introduction
end note
ASPSP Authorisation Server-> ASPSP Authorisation Server: Bind selected Accounts to AccountRequestId
ASPSP Authorisation Server -> PSU: HTTP 302 (Found); Location: redirect-uri (authorization-code, id_token, state)
PSU -> AISP: HTTP GET redirect-uri (authorization-code, id_token, state)
AISP->AISP: Validate signature on id_token
note right of AISP
    Validate the id_token by using the ASPSP's public key.
    ASPSP certificate will be identified using the kid claim
    in the JOSE header of the id_token
end note
AISP->AISP: Validate authorization-code using id_token (c_hash)
AISP->AISP: Validate state using id_token (s_hash)
AISP->AISP: Validate nonce using id_token
note right of AISP:
    Exchange authorization-code for access token.
end note
    
    
    
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
AISP -> ASPSP Authorisation Server: HTTP POST /token (client authentication credentials,\nauthorization-code, grant_type, redirect_uri)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials,\nauthorization-code
    ASPSP Authorisation Server->ASPSP Authorisation Server: Generate access-token
    ASPSP Authorisation Server->ASPSP Authorisation Server: Bind access-token to AccountRequestId
    note right of ASPSP Authorisation Server
        Implies an association of Accounts to access-token
    end note
    ASPSP Authorisation Server->ASPSP Resource Server: Update account-requests Status to Authorised
    ASPSP Resource Server->ASPSP Authorisation Server:OK
    note right of ASPSP Authorisation Server
        Implementation of how the resource is updated is ASPSP specific (There
        is no standardised API for this)
    end note
alt Access Token
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token (scope:accounts)
  
else Optional Refresh Token
    ASPSP Authorisation Server->ASPSP Authorisation Server: Generate Refresh Token
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token, refresh-token (scope:accounts)
  
end
     
      
note over PSU, ASPSP Resource Server
Step 4: Request data
end note
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP<->AISP: Retrieve access-token
note left of AISP
    Retrieve the access-token that was issued in Step [42].
    The access-token is  linked with consented Accounts
    from Steps [27] and [39]
end note
  
alt Valid Access Token
    AISP -> ASPSP Resource Server: GET /accounts (access-token - scope:accounts)
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
    ASPSP Resource Server -> AISP: HTTP 200 (OK), List of accounts containing AccountId(s)
    AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions (access-token - scope:accounts)
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
 
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token bound to AccountId
    ASPSP Resource Server -> AISP: HTTP 200 (OK), List of transactions
else Expired Access Token
    AISP->AISP: Retrieve Refresh Token from [44]
    AISP->ASPSP Authorisation Server:HTTP POST /token (client authentication credentials,\ngrant_type=refresh_token,refresh_token=[58],\nscope=openid accounts)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials,\refresh_token
    ASPSP Authorisation Server->ASPSP Authorisation Server: Generate Access Token and Refresh Token
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token, refresh-token (scope:accounts)
    AISP -> ASPSP Resource Server: GET /accounts (access-token - scope:accounts)
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
    ASPSP Resource Server -> AISP: HTTP 200 (OK), List of accounts containing AccountId(s)
    AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions (access-token - scope:accounts)
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token matches client SSL cert
    ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
    ASPSP Resource Server->ASPSP Resource Server: Validate access-token bound to AccountId
    ASPSP Resource Server -> AISP: HTTP 200 (OK), List of transactions
else Account Request - Get Status
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
    
    note left of AISP
        Client Credentials Grant
    end note
    AISP->ASPSP Authorisation Server: POST /token (client authentication credentials, scope:accounts)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials, scope
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token (scope:accounts)
    
    
    AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    AISP->AISP: Retrieve AccountRequestId from [16]
    AISP -> ASPSP Resource Server: GET /account-requests/{AccountRequestId} (access-token - scope:accounts)
        ASPSP Resource Server->ASPSP Resource Server: Validate access token
        ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
        ASPSP Resource Server->ASPSP Resource Server: Validate clientId matches client SSL cert
        ASPSP Resource Server->ASPSP Resource Server: Lookup AccountRequestId resource
     
    ASPSP Resource Server -> AISP: HTTP 200 (OK), AccountRequest Status
 
else Account Request- PSU removes consent at a later point in time with the AISP
PSU -> AISP: Establish TLS 1.2
PSU -> AISP: Remove Consent
 
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
    
    note left of AISP
        Client Credentials Grant
    end note
    AISP->ASPSP Authorisation Server: POST /token (client authentication credentials, scope:accounts)
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate client authentication credentials, scope
    ASPSP Authorisation Server->ASPSP Authorisation Server: Validate clientId matches client SSL cert
    ASPSP Authorisation Server -> AISP: HTTP 200 (OK) access-token (scope:accounts)
    
    
    AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
    AISP->AISP: Retrieve AccountRequestId from [16]
    AISP -> ASPSP Resource Server: DELETE /account-requests/{AccountRequestId} (access-token - scope:accounts)
        ASPSP Resource Server->ASPSP Resource Server: Validate access token
        ASPSP Resource Server->ASPSP Resource Server: Validate scope:accounts
        ASPSP Resource Server->ASPSP Resource Server: Validate clientId matches client SSL cert
        ASPSP Resource Server->ASPSP Resource Server: Delete AccountRequestId resource
     
    ASPSP Resource Server -> AISP: HTTP 204 (No Content)
    AISP->PSU: Consent Removed
end

...

Versions Compared

Old Version 3

New Version 4

Key

Account API Specification