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 multiple recurring payments

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

Creates an initiation resource for a partial payment initiation for the related authorised payment resource at the ASPSP. The initiation might be either then be booked afterwards by the ASPSP or need an explicit confirmation by the API Client.

Parameter Type Description
extended-payment-service4 string , required

Extended Payment Initiation Service. The default list is: * multiple-recurring-payments for XMRPIS

Allowed values: multiple-recurring-payments

Example: multiple-recurring-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

Client-Explicit-Confirmation-Requested boolean , optional

If it equals "true", and if an explicit confirmation is supported by the ASPSP, then the related initiation will only be executed after an additional confirmation request. If it equals "true", and if an explicit confirmation is not supported by the ASPSP, then the related request will be rejected. If it equals "false" or if an explicit confirmation is not supported by the ASPSP or if not used by the API Client, then the related initiation needs no further action on the API to be executed.

Example: true

Field Type Description
instructedAmount object , required

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.

confirmationExpiryDateTime string , optional

The ASPSP shall provide this attribute, if the explicit confirmation is supported by the ASPSP and if the Client-Explicit-Confirmation-Requested equals true. This attribute implies that an explicit confirmation by the API Client is still outstanding.

Format: date-time

estimatedInterbankSettlementAmount object , optional

The estimated amount to be transferred to the payee.

_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. 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.