OpenFinance
Development Portal

openFinance API Framework XS2A API as PSD2 Interface Implementation Guidelines - Payment Initiation Service (2.3)

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 payment initiation flow depends heavily on the SCA approach implemented by the ASPSP. The most complex flow is the flow for the Embedded SCA Approach, which further differs on whether there are various authentication methods available for the PSU. In the following, the different API flows are provided as an overview for these different scenarios. Remark: The flows do not always cover all variances or complexities of the implementation and are exemplary flows.

Cancel payment

DELETE /v2/{payment-service}/{payment-product}/{paymentId}

Initiates the cancellation of a payment See "XS2A API as PSD2 Interface Implementation Guidelines ", section "Payment Cancellation Request".

Path parameters

Parameter Type Description
payment-service string , required

Payment service: Possible values are: * payments * bulk-payments * periodic-payments

Allowed values: payments, bulk-payments, periodic-payments

Example: payments
payment-product string , required

The payment product, under which the payment under paymentId has been initiated. It shall be checked by the ASPSP, if the payment-product is matching the payment initiation addressed by paymentId.

Allowed values: sepa-credit-transfers, instant-sepa-credit-transfers, target-2-payments, cross-border-credit-transfers, pain.001-sepa-credit-transfers, pain.001-instant-sepa-credit-transfers, pain.001-target-2-payments, pain.001-cross-border-credit-transfers, pain.001-proprietary-credit-transfers

Example: sepa-credit-transfers
paymentId string , required

Resource identification of the related payment.

Example: fe7552ee-0728-4bd1-baf7-94942331e478

Allowed length: max: 70

Header parameters

Header Type Description
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}$
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
Client-SCA-Approach-Preference string , optional

A comma separated list of attributes, where the first entry will have a higher priority than the next or to every SCA Approach which is not indicated at all, e.g. "decoupled, redirect, embedded, signature" or "decoupled" This attribute may be ignored by the ASPSP

Example: decoupled, redirect, embedded

Allowed length: max: 35
Client-Redirect-URI string , optional

URI the transaction flow returns to after a redirect. Required for the redirect SCA approach.

Example: https://exampleclient.com/redirectUri?clientEvent=11111111

Format: uri
Client-Nok-Redirect-URI string , optional

If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the Client-Redirect-URI in case of a negative result of the redirect SCA method. This might be ignored by the ASPSP.

Example: https://exampleclient.com/NokUri?clientEvent=11111111

Format: uri
Client-Explicit-Authorisation-Preferred boolean , optional

If it equals "true", the API Client prefers to start the authorisation process separately, e.g. because of the usage of a signing basket or because of asynchronous authorisation. This preference might be ignored by the ASPSP, if a signing basket is not supported as functionality or if asynchronous authorisation is not supported. If it equals "false" or if the parameter is not used, there is no preference of the API Client. This especially indicates that the API Client assumes a direct authorisation of the transaction in the next step, without using a signing basket.

Example: true
Client-Notification-URI string , optional

URI for the Endpoint of the Client API to which the status of the resource should be sent. This header field may by ignored by the ASPSP if the resource status push function is not supported for the related API client.

Example: https://exampleclient.com/NotificationUri?clientEvent=11111111
Client-Notification-Content-Preferred string , optional

The string has the form status=X1, ..., Xn where Xi is one of the constants SCA, PROCESS, LAST and where constants are not repeated. The usage of the constants supports the of following semantics: SCA: A notification on every change of the scaStatus attribute for all related authorisation processes is preferred by the API Client. PROCESS: A notification on all changes of consentStatus or transactionStatus attributes is preferred by the API Client. LAST: Only a notification on the last consentStatus or transactionStatus as available in the XS2A interface is preferred by the API Client. This header field may be ignored, if the ASPSP does not support resource notification services for the related API Client.

Example: status=SCA
Client-Brand-Logging-Information string , optional

This header might be used by API Clients to inform the ASPSP about the brand used by the API Client towards the PSU. This information is meant for logging entries to enhance communication between ASPSP and PSU or ASPSP and API Client. This header might be ignored by the ASPSP.

Example: ClientBrandB

Allowed length: max: 140
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

Responses

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

Field Type Description
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 "startAuthorisationWithAuthenticationMethodSelection" contained in the response body. These methods shall be presented towards the PSU for selection by the TPP.
challengeData object , optional

It is contained in addition to the data element "chosenScaMethod" if challenge data is needed for SCA. In rare cases this attribute is also used in the context of the "startAuthorisationWithPsuAuthentication" or "startAuthorisactionWithEncryptedPsuAuthentication" link.
chosenScaMethod object , optional

This data element is only contained in the response if the ASPSP has chosen the Embedded SCA Approach, if the PSU is already identified e.g. with the first relevant factor or alternatively an access token, if SCA is required and if the authentication method is implicitly selected.
transactionStatus string , required

ISO 20022 transaction status code.

Allowed values: ACCC, ACCP, ACSC, ACSP, ACTC, ACWC, ACWP, RCVD, PDNG, RJCT, CANC, ACFC, PATC, PART, PRES, RVCM, RVNC, RCVC

Example: ACCC
_links object , optional

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 or response message for other requests which need authorisation. 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.