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.

Create secured payment

POST /v2/secured-payments/{payment-product}

Creates an extended payment resource for secured payments at the ASPSP for the XFPIS service.

Path parameters

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

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
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
Consent-ID string , optional

Identifier of the consent that authorises this access, as returned when the consent was created.

Example: 123cons456

Allowed length: max: 70

Body payload

Field Type Description
creditor object , required

Party to which an amount of money is due.
purposeCode string , optional

Specifies the purpose of the instruction based the code set ExternalPurpose1Code from ISO 20022.

Allowed values: BKDF, BKFE, BKFM, BKIP, BKPP, CBLK, CDCB, CDCD, CDCS, CDDP, CDOC, CDQC, ETUP, FCOL, MTUP, ACCT, CASH, COLL, CSDB, DEPT, INTC, INTP, LIMA, NETT, BFWD, CCIR, CCPC, CCPM, CCSM, CRDS, CRPR, CRSP, CRTL, EQPT, EQUS, EXPT, EXTD, FIXI, FWBC, FWCC, FWSB, FWSC, MARG, MBSB, MBSC, MGCC, MGSC, OCCC, OPBC, OPCC, OPSB, OPSC, OPTN, OTCD, REPO, RPBC, RPCC, RPSB, RPSC, RVPO, SBSC, SCIE, SCIR, SCRP, SHBC, SHCC, SHSL, SLEB, SLOA, SWBC, SWCC, SWPT, SWSB, SWSC, TBAS, TBBC, TBCC, TRCP, AGRT, AREN, BEXP, BOCE, COMC, CPYR, GDDS, GDSV, GSCB, LICF, MP2B, POPE, ROYA, SCVE, SERV, SUBS, SUPP, TRAD, CHAR, COMT, MP2P, ECPG, ECPR, ECPU, EPAY, CLPR, COMP, DBTC, GOVI, HLRP, HLST, INPC, INPR, INSC, INSU, INTE, LBRI, LIFI, LOAN, LOAR, PENO, PPTI, RELG, RINP, TRFD, FORW, FXNT, ADMG, ADVA, BCDM, BCFG, BLDM, BNET, CBFF, CBFR, CCRD, CDBL, CFEE, CGDD, CORT, COST, CPKC, DCRD, DSMT, DVPM, EDUC, FACT, FAND, FCPM, FEES, GIFT, GOVT, ICCP, IDCP, IHRP, INSM, IVPT, MCDM, MCFG, MSVC, NOWS, OCDM, OCFG, OFEE, OTHR, PADD, PTSP, RCKE, RCPT, REBT, REFU, RENT, REOD, RIMB, RPNT, RRBN, RRCT, RRTP, RVPM, SLPI, SPLT, STDY, TBAN, TBIL, TCSC, TELI, TMPG, TPRI, TPRP, TRNC, TRVC, WEBI, IPAY, IPCA, IPDO, IPEA, IPEC, IPEW, IPPS, IPRT, IPU2, IPUW, ANNI, CAFI, CFDI, CMDT, DERI, DIVD, FREX, HEDG, INVS, PRME, SAVG, SECU, SEPI, TREA, UNIT, FNET, FUTR, ANTS, CVCF, DMEQ, DNTS, HLTC, HLTI, HSPC, ICRF, LTCF, MAFC, MARF, MDCS, VIEW, CDEP, SWFP, SWPP, SWRS, SWUF, ADCS, AEMP, ALLW, ALMY, BBSC, BECH, BENE, BONU, CCHD, COMM, CSLP, GFRP, GVEA, GVEB, GVEC, GVED, GWLT, HREC, PAYR, PEFC, PENS, PRCP, RHBS, SALA, SPSP, SSBE, LBIN, LCOL, LFEE, LMEQ, LMFI, LMRK, LREB, LREV, LSFL, ESTX, FWLV, GSTX, HSTX, INTX, NITX, PTXP, RDTX, TAXS, VATX, WHLD, TAXR, B112, BR12, TLRF, TLRR, AIRB, BUSB, FERB, RLWY, TRPT, CBTV, ELEC, ENRG, GASB, NWCH, NWCM, OTLC, PHON, UBIL, WTER, BOND, CABD, CAEQ, CBCR, DBCR, DICL, EQTS, FLCR, EFTC, EFTD, MOMA, RAPI, GAMB, LOTT, AMEX, SASW, AUCO, PCOM, PDEP, PLDS, PLRF, GAFA, GAHO, CPEN, DEPD, RETL, DEBT
creditorAgent object , optional

Financial institution servicing an account for the creditor.
ultimateDebtor object , optional

Ultimate party that owes an amount of money to the (ultimate) creditor. Restriction to the schema are applied depending on the product.
creditorAccount object , required

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.
instructedAmount object , required

Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.
ultimateCreditor object , optional

Ultimate party to which an amount of money is due.
categoryPurposeCode string , optional

Specifies the high level purpose of the instruction based on a set of pre-defined categories; provided as code.

Allowed values: BONU, CASH, CBLK, CCRD, CORT, DCRD, DIVI, DVPM, EPAY, FCIN, FCOL, GP2P, GOVT, HEDG, ICCP, IDCP, INTC, INTE, LBOX, LOAN, MP2B, MP2P, OTHR, PENS, RPRE, RRCT, RVPM, SALA, SECU, SSBE, SUPP, TAXS, TRAD, TREA, VATX, WHLD, SWEP, TOPG, ZABA, VOST, FCDT, CIPC, CONC
paymentIdentification object , optional

Set of elements used to reference a payment instruction.
remittanceInformationStructured array[object] , optional

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in a structured form.
remittanceInformationUnstructured array[string] , optional

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts' receivable system, in an unstructured form.

Example: ["{\"Ref Number Merchant\"}"]
debtor object , optional

Party that owes an amount of money to the (ultimate) creditor.
debtorAccount object , required

Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.
requestedExecutionDate string , optional

Date at which the initiating party requests the clearing agent to process the payment.

Format: date
requestedExecutionDateTime string , optional

Date and time at which the initiating party requests the clearing agent to process the payment.

Format: date-time

Responses

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

Field Type Description
paymentId string , required

resource identification of the generated payment initiation resource.
securedBy string , optional

The way of securing the funds for the transaction amount.

Allowed values: reservationOfFunds, creditLine, bankGuarantee, consumerLoan
psuMessage string , optional

Text to be displayed to the PSU.
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
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.
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.
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.
transactionStatus string , required

Payment transaction status.

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.
estimatedInterbankSettlementAmount object , optional

The estimated amount to be transferred to the payee.
_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.