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.

Get payment status

GET /v2/{payment-service}/{payment-product}/{paymentId}/status

Reads the status of a payment initiation. See "XS2A API as PSD2 Interface Implementation Guidelines ", section "Get Transaction Status Request".

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 Type Description
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

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

Field Type Description
ownerNames array[object] , optional

List of owner names. Should only be delivered after successful SCA. Could be restricted to the current PSU by the ASPSP.

psuMessage string , optional
reasonCode string , optional

Additional information on the reason for e.g. rejecting the request

Allowed values: AM04, AM21, BEXX, CN01, DS0C, DS0D, DS0A, DS04, FOCR, SL11, TKSP, TKXP, AM02, DT05, AC05, AC06, DS0K, DT01, UPAY, EOL1

fundsAvailable boolean , optional

This data element is contained, if supported by the ASPSP, if a funds check has been performed and if the transactionStatus is "ACTC", "ACWC" or "ACCP".

transactionFees object , optional

Might be used by the ASPSP to transport the total transaction fee relevant in case of an underlying payment initiation service. This field includes the entry of the currencyConversionFees if applicable.

apiClientMessages array[object] , optional

Errors and warnings describing why the request failed. See Errors for the message format.

reasonProprietary string , optional

Proprietary additional information on the reason for e.g. rejecting the request. Remark: If an ISO Code is available it should be used instead of Proprietary Reasons. Further restrictions could be defined by API Access Schemes.

transactionStatus string , required

In case where the Payment Initiation Request was JSON encoded, the status is returned in this JSON based encoding. Remark: If the PSU does not complete a required SCA within the required timeframe the payment resource's status must be set to "RJCT". Particularly, if a multi-level-SCA is required and the number of successful SCAs during the required timeframe is insufficient, the status must also be set to "RJCT".

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

estimatedTotalAmount object , optional

The amount which is estimated to be debted from the debtor account in case of an underlying payment initiation service. 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, in case of an underlying payment initiation service.

estimatedInterbankSettlementAmount object , optional

The estimated amount to be transferred to the payee in case of an underlying payment initiation service.

_links object , optional

Should refer to next steps if a potential situation blocking the finalisation of the payment can be resolved via the interface e.g. for re-submission of credentials.