OpenFinance
Development Portal

openFinance API Framework XS2A API as PSD2 Interface Implementation Guidelines - Extended Payment Initiation Service (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 specific function in the Extended Payment Initiation Services is to make the initiation phase more flexible, i.e. * separate authorisation and actual initiation processes as well as * unbundle risk management functionality from the actual payment initiation, but already apply e.g. limit and balance checks during the authorisation and hence * potentially secure the future payment initiation in addition.

Initiate deferred payment

POST /v2/{extended-payment-service1}/{payment-product}/{paymentId}/initiations

Creates an initiation for a (partial) deferred payment initiation for the related authorised payment resource at the ASPSP.

Parameter Type Description
extended-payment-service1 string , required

Extended Payment Initiation Service. The default list is: * deferred-payments for XDPIS * secured-deferred-payments for XDFPIS * multiple-deferred-payments for XMDPIS * secured-multiple-deferred-payments for XMDFPIS

Allowed values: deferred-payments, secured-deferred-payments, multiple-deferred-payments, secured-multiple-deferred-payments

Example: deferred-payments

payment-product string , required

The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products are supported: - For request bodies with JSON encoding: -- sepa-credit-transfers -- micro-sepa-credit-transfers -- instant-sepa-credit-transfers -- target-2-payments -- cross-border-credit-transfers The ASPSP will publish which of the payment products/endpoints will be supported. For definitions of basic non euro generic products see [oFA PFDom]. Further products might be published by the ASPSP within its XS2A documentation. These new product types will end in further endpoints of the XS2A Interface.

Allowed values: sepa-credit-transfers, micro-sepa-credit-transfers, instant-sepa-credit-transfers, target-2-payments, cross-border-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
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

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, EUDIW

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

API-Contract-ID string , optional

Might be mandated by the ASPSP, if a commercial agreement is needed for the usage of the service.

Example: 99435d7f-ad87-4aec-a2ae-99ddcb1f6555

Format: uuid

PSU-IP-Address string , required

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

Field Type Description
closingFlag boolean , required

If true, then the TPP indicates that this is the last initiation on the related payment resource. As a consequence, the mechanism for securing the payment (e.g. reservation of funds) is closed in the ASPSP system.

instructedAmount object , optional

Amount requested from the API client to be executed by the ASPSP. Mandatory for XDPIS, XDFPIS, XRPIS and XRFPIS. If not contained in a XMDPIS service, then this is a dedicated closing transaction. This amount shall be smaller or equal to the amount still being reserved in the XDPIS/XDFPIS/XMPIS/XMFPIS case (current reservedAmount)

paymentIdentification object , optional

If this attribute is provided, then it will be used by the ASPSP in the related credit transfer for payment identification.

remittanceInformationStructured array[object] , optional

The supported sub structure will depend on the underlying payment product. If this attribute is provided, then it will be used by the ASPSP in the related credit transfer for remittance information.

remittanceInformationUnstructured array[string] , optional

If this attribute is provided, then it will be used by the ASPSP in the related credit transfer for remittance information.

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

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

initiationId string , required

Unique identification of the deferred payment initiation.

transactionFees object , optional

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

reasonProprietary string , optional

Proprietary additional information on the reason for e.g. rejecting the request.

transactionStatus string , required

The status of the addressed deferred payment initiation.

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. Note: This amount includes fees.

currencyConversionFee object , optional

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

transactionFeeIndicator boolean , optional

If equals "true", the transaction will involve specific transaction cost as shown by the ASPSP in their public price list or as agreed between ASPSP and PSU. If equals "false", the transaction will not involve additional specific transaction costs to the PSU unless the fee amount is given specifically in the data elements transactionFees and/or currencyConversionFees. If this data element is not used, there is no information about transaction fees unless the fee amount is given explicitly in the data element transactionFees and/or currencyConversionFees.

remainingAuthorisedAmount object , optional

The amount still available for further following deferred payment initiations. Only used in case of multiple deferred payments.

estimatedInterbankSettlementAmount object , optional

The estimated amount to be transferred to the payee.