OpenFinance
Development Portal

Authorisation API for V2.x (2.1)

The Berlin Group - A European Standards Initiative | info@: info@berlin-group.org | URL: https://www.berlin-group.org/

License: Creative Commons Attribution 4.0 International Public License

The Authorisation API provides services for managing Strong Customer Authentication (SCA) authorisation processes for various resource types including consents, payments, and other financial services. The API supports starting authorisation processes, updating PSU data, and checking authorisation status in compliance with PSD2 and EBA-RTS requirements.

Update PSU data

PUT /v2/{resource-path}/{resourceId}/{authorisation-category}/{authorisationId}

Updates the addressed authorisation sub-resource data on the server by PSU data if requested by the ASPSP.

Parameter Type Description
resource-path string , required

This resource path can be a one-level parameter {service} or a two-level parameter {service}/{product-type}, where * {service} stands for the service type of the related business transaction, e.g. /payments or /consents source. * {product-type} stands for the product-type of the related business transaction where applicable, e.g. sepa-credit-transfers in the case of payments or account-access in case of consents.

Example: consents/account-access

resourceId string , required

Resource identification of the related payment initiation, signing basket, consent, subscription or other related business transaction resource.

Example: 1234-resource-567

Allowed length: max: 70

authorisation-category string , required

The following two categories are supported: * authorisations: used in case of an authorisation of the related business transaction. * cancellation-authorisations: used in case of the cancellation authorisation of the related business transaction. Used only if applicable to the addressed {service}

Allowed values: authorisations, cancellation-authorisations

Example: authorisations

authorisationId string , required

Resource identification of the related SCA.

Example: 123auth456

Allowed length: max: 70

Header Type Description
PSU-IP-Address string , optional

IP address of the PSU's device as forwarded by the TPP. If unavailable, use the IP address the TPP used for this request.

Example: 192.168.8.78

Format: ipv4

PSU-IP-Port string , optional

The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.

Example: 1234

PSU-Accept string , optional

The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

Example: application/json

PSU-Accept-Charset string , optional

The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

Example: *

PSU-Accept-Encoding string , optional

The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

Example: *

PSU-Accept-Language string , optional

The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.

Example: en-gb,en;0.8

PSU-User-Agent string , optional

The forwarded Agent header field of the HTTP request between PSU and TPP, if available.

Example: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) Gecko/20100101 Firefox/54.0

PSU-Http-Method string , optional

HTTP method used at the PSU ? TPP interface, if available. Valid values are: * GET * POST * PUT * PATCH * DELETE

Allowed values: GET, POST, PUT, PATCH, DELETE

Example: GET

PSU-Device-ID string , optional

UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID needs to be unaltered until removal from device.

Example: 99435c7e-ad88-49ec-a2ad-99ddcb1f5555

Format: uuid

PSU-Geo-Location string , optional

The forwarded Geo Location of the corresponding http request between PSU and TPP if available.

Example: GEO:52.506931;13.144558

Pattern: ^GEO:-?[0-9]{1,2}\.[0-9]{6};-?[0-9]{1,3}\.[0-9]{6}$

Digest string , optional

Integrity hash of the request body in the form SHA-256=<base64>. For an empty body, use the hash of an empty string. See Signing requests for how the Digest and signature are built.

Example: SHA-256=hl1/Eps8BEQW58FJhDApwJXjGY4nr1ArGDHIT25vq6A=

x-jws-signature string , optional

Detached JSON Web Signature over the signed request headers and body. See Signing requests for how it is constructed.

X-Request-ID string , required

Unique ID of the request, set by the initiating party and echoed back in the response.

Example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721

Format: uuid

Body-Sig-Profile string , optional

Indicates the signature profile used for signing (parts of) the body. Shall be used if the body is signed.

Allowed values: JAdES_JS, XAdES, EMV_AC

Example: XAdES

Body-Enc-Profile string , optional

Indicates the encryption profile used for the encryption of (parts of) the body.

Allowed values: JWE_CS, XML_ENC

Example: JWE_CS

Body-Enc-List string , optional

Contains a List of names of data elements/ attributes of the body which contain encrypted information

Example: BODY

PSU-ID string , optional

Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP's documentation. It might be contained even if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session. In this case the ASPSP might check whether PSU-ID and token match, according to ASPSP documentation.

Example: PSU-1234

Allowed length: max: 140

PSU-ID-Type string , optional

Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. In this case, the mean and use are then defined in the ASPSP's documentation.

Example: PSU-ID-TYPE_C

Allowed length: max: 35

PSU-Corporate-ID string , optional

Might be mandated in the ASPSP's documentation. Only used in a corporate context.

Example: PSU-CORP-ID1234

Allowed length: max: 140

PSU-Corporate-ID-Type string , optional

Might be mandated in the ASPSP's documentation. Only used in a corporate context.

Example: PSU-CORP-ID-TYPE_A

Allowed length: max: 35

Field Type Description
psuData object , required

The password, orencryptedPassword, subfield is used, depending depending on encryption requirements of the ASPSP as indicated in the corresponding hyperlink contained in the preceding response message of the ASPSP. The related encryption requirements are defined in document "Protocol Functions and Security Measures".

Select a status code to see the structure and an example of the response.

Field Type Description
scaStatus string , required

See document "openFinance API Framework Data Dictionary", section "SCA Status" for more details.

Allowed values: received, psuIdentified, psuAuthenticated, scaMethodSelected, started, unconfirmed, finalised, failed, exempted

psuMessage string , optional

Text to be displayed to the PSU.

scaMethods array[object] , optional

This data element might be contained, if SCA is required and if the PSU has a choice between different authentication methods. Depending on the risk management of the ASPSP this choice might be offered before or after the PSU has been identified with the first relevant factor, or if an access token is transported. If this data element is contained, then there is also a hyperlink of type "selectAuthenticationMethod" contained in the response body. These methods shall be presented towards the PSU for selection by the API Client.

transactionFees object , optional

Might be used by the ASPSP to transport the total transaction fee relevant for the underlying payments. This field includes the entry of the currencyConversionFees if applicable.

estimatedTotalAmount object , optional

The estimated amount to be transferred to the payee. Note: This amount includes fees.

currencyConversionFees object , optional

Might be used by the ASPSP to transport specific currency conversion fees related to the initiated credit transfer.

estimatedInterbankSettlementAmount object , optional

The estimated amount to be transferred to the payee in case of a payment resource.

_links object , required

A list of hyperlinks to be recognised by the API Client. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request. The potential links for this response message are generically defined in [oFA SMPF] for all Transaction Initiation Response messages. These links will also be contained in the related Open API files. Remark: All links can be relative or full links, to be decided by the ASPSP.