Skip to content

Instantly share code, notes, and snippets.

@ioggstream

ioggstream/StetPSD2API-1.4.yaml

Created March 22, 2019 13:34
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save ioggstream/07ac4fe6cfa97525dc64f43febe31ce3 to your computer and use it in GitHub Desktop.
Save ioggstream/07ac4fe6cfa97525dc64f43febe31ce3 to your computer and use it in GitHub Desktop.
Download ZIP
STET OpenBanking API
Raw
StetPSD2API-1.4.yaml
openapi: 3.0.0
info:
version: 1.4.1.3
title: 'PSD2 ASPSP services for AISP, PISP and CBPII.'
description: >
This API intends to provide an interface between
- Account Servicing Payment Service Providers (ASPSP)
- Third Party (Payment Service) Providers (TPP)
TPP may act with different roles as described below:
- Account Information Service Providers (AISP)
- Payment Initiation Service Providers (PISP)
- Card Based Payment Instrument Issuers (CBPII)
The Payment Service User (PSU) is the owner of the accounts held by the
ASPSP and gives accreditations to the TPP in order to access his accounts
information or initiates payment from these accounts
The API is designed on a REST model using JSON structures.
The Richardson Maturity Model is applied on level three using HAL HYPERMEDIA
links
contact:
name: STET
url: 'https://www.stet.eu/en/psd2/'
email: psd2@stet.eu
license:
name: Creative Commons Attribution 3.0 France (CC BY 3.0 FR)
paths:
/accounts:
get:
operationId: accountsGet
tags:
- AISP
summary: Retrieval of the PSU accounts (AISP)
description: |
<h3>Description</h3>
This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected.
Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role.</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication</li>
<li>The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
</ul>
<h3>Business Flow</h3>
The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts.
The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list.
The result may be subject to pagination in order to avoid an excessive result set.
Each payment account will be provided with its characteristics.
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: >
The ASPSP return a PSU context
- listing the accounts that have been made available to the AISP by
the PSU and,
- for each of these accounts, the further transactions that have
been enabled by the PSU through HYPERMEDIA links.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalAccounts'
'204':
$ref: '#/components/responses/204'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
'/accounts/{accountResourceId}/balances':
get:
operationId: accountsBalancesGet
description: |
<h3>Description</h3>
This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP
<ul style="list-style-type:circle;">
<li>At this step, the ASPSP has delivered an OAUTH2 &ldquo;Authorization Code&rdquo; or &ldquo;Resource Owner Password&rdquo; access token to the TPP (cf. &sect; 3.4.2).</li>
</ul>
</li>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication</li>
<li>The TPP has presented its OAUTH2 &ldquo;Authorization Code&rdquo; or &ldquo;Resource Owner Password&rdquo; access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. &sect; 3.4.2) if any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
<li>The TPP has previously retrieved the list of available accounts for the PSU</li>
</ul>
<h3>Business flow</h3>
The AISP requests the ASPSP on one of the PSU&rsquo;s accounts.<br />
The ASPSP answers by providing a list of balances on this account.
<ul>
<li>The ASPSP must provide at least the accounting balance on the account.</li>
<li>The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.</li>
<li>Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.</li>
</ul>
summary: Retrieval of an account balances report (AISP)
tags:
- AISP
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/AccountResourceIdentification'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: The ASPSP answers with a list of account balances
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalBalances'
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
'/accounts/{accountResourceId}/transactions':
get:
operationId: accountsTransactionsGet
description: |
<h3>Description</h3>
This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification.
The request may use some filter parameter in order to restrict the query
<ul>
<li>on a given imputation date range</li>
<li>past a given incremental technical identification</li>
</ul>
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication </li>
<li>The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
<li>The TPP has previously retrieved the list of available accounts for the PSU</li>
</ul>
<h3>Business flow</h3>
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria.
The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.
summary: Retrieval of an account transaction set (AISP)
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
tags:
- AISP
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/AccountResourceIdentification'
- $ref: '#/components/parameters/FromImputationDate'
- $ref: '#/components/parameters/ToImputationDate'
- $ref: '#/components/parameters/AfterEntryReference'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: Complete transactions response
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalTransactions'
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/consents:
put:
operationId: consentsPut
tags:
- AISP
summary: Forwarding the PSU consent (AISP)
description: |
<h3>Description</h3>
In the mixed detailed consent on accounts
<ul>
<li>the AISP captures the consent of the PSU</li>
<li>then it forwards this consent to the ASPSP</li>
</ul>
This consent replaces any prior consent that was previously sent by the AISP.
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role.</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication</li>
<li>The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
</ul>
<h3>Business Flow</h3>
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available.
The AISP forwards these settings to the ASPSP.
The ASPSP answers by HTTP201 return code.
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'201':
description: Created
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
'503':
$ref: '#/components/responses/503'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Access'
description: List of consents granted to the AISP by the PSU.
/end-user-identity:
get:
operationId: EndUserIdentityGet
tags:
- AISP
summary: Retrieval of the identity of the end-user (AISP)
description: |
<h3>Description</h3>
This call returns the identity of the PSU (end-user).
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role.</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication</li>
<li>The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
</ul>
<h3>Business Flow</h3>
The AISP asks for the identity of the PSU.
The ASPSP answers with the identity, i.e. first and last names of the end-user.
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: |
The ASPSP returns the identity of the PSU
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalEndUserIdentity'
'204':
$ref: '#/components/responses/204'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/trusted-beneficiaries:
get:
operationId: trustedBeneficiariesGet
tags:
- AISP
summary: Retrieval of the trusted beneficiaries list (AISP)
description: |
<h3>Description</h3>
This call returns all trusted beneficiaries that have been set by the PSU.
Those beneficiaries can benefit from an SCA exemption during payment initiation.
The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the AISP role.</li>
<li>The TPP and the PSU have a contract that has been enrolled by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication</li>
<li>The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.</li>
<li>The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.</li>
</ul>
<h3>Business Flow</h3>
The AISP asks for the trusted beneficiaries list.
The ASPSP answers with a list of beneficiary details structure.
security:
- accessCode:
- aisp
- resourceOwnerIdentification:
- aisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: |
The ASPSP returns the list of whitelisted beneficiaries
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalBeneficiaries'
'204':
$ref: '#/components/responses/204'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'501':
$ref: '#/components/responses/501'
/funds-confirmations:
post:
operationId: fundsConfirmationsPost
tags:
- CBPII
summary: Payment coverage check request (CBPII)
description: >
<h3>Description</h3>
The CBPII can ask an ASPSP to check if a given amount can be covered by
the liquidity that is available on a PSU cash account or payment card.
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the CBPII role</li>
<li>The TPP and the PSU have a contract that has been registered by the ASPSP</li>
<ul>
<li>At this step, the ASPSP has delivered an "Authorization Code", a "Resource Owner Password" or a "Client Credential" OAUTH2 access token to the TPP (cf. § 3.4.2).</li>
<li>Each ASPSP has to implement either the "Authorization Code"/"Resource Owner Password" or the "Client Credential" OAUTH2 access token model.</li>
<li>Doing this, it will edit the [security] section on this path in order to specify which model it has chosen</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication </li>
<li>The TPP has presented its OAUTH2 "Authorization Code", "Resource Owner Password" or "Client Credential" access token which allows the ASPSP to identify the relevant PSU.</li>
</ul>
<h3>Business flow</h3>
The CBPII requests the ASPSP for a payment coverage check against either
a bank account or a card primary identifier.
The ASPSP answers with a structure embedding the original request and
the result as a Boolean.
security:
- accessCode:
- cbpii
- resourceOwnerIdentification:
- cbpii
- clientCredentials:
- cbpii
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: payment coverage request
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
Digest:
description: Digest of the body
schema:
type: string
Signature:
description: >
http-signature of the response (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL
aiming to provide the relevant Qualified Certificate.
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalPaymentCoverageReport'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCoverageRequestResource'
description: parameters of a payment coverage request
required: true
/payment-requests:
post:
operationId: paymentRequestsPost
tags:
- PISP
summary: Payment request initiation (PISP)
description: |
<h3>Description</h3>
The following use cases can be applied:
<ul>
<li>payment request on behalf of a merchant</li>
<li>transfer request on behalf of the account's owner</li>
<li>standing-order request on behalf of the account's owner</li>
</ul>
<h4>Data content</h4>
A payment request or a transfer request might embed several payment instructions having
<ul>
<li>one single execution date or multiple execution dates</li>
<ul>
<li>case of one single execution date, this date must be set at the payment level</li>
<li>case of multiple execution dates, those dates must be set at each payment instruction level</li>
</ul>
<li>one single beneficiary or multiple beneficiaries</li>
<ul>
<li>case of one single beneficiary, this beneficiary must be set at the payment level</li>
<li>case of multiple beneficiaries, those beneficiaries must be set at each payment instruction level</li>
</ul>
</ul>
Having at the same time multiple beneficiaries and multiple execution date might not be a relevant business case, although it is technically allowed.<br/>
Each implementation will have to specify which business use cases are actually supported.<br/>
A standing order request must embed one single payment instruction and must address one single beneficiary.
<ul>
<li>The beneficiary must be set at the payment level</li>
<li>The standing order specific characteristics (start date, periodicity...) must be set at the instruction level</li>
</ul>
Payment request can rely for execution on different payment instruments:
- SEPA Credit Transfer (SCT)
- Domestic Credit Transfer in a non Euro-currency
- International payment
The following table indicates how to use the different fields, depending on the payment instrument:
<table border="1">
<thead>
<tr>
<td>Structure</td>
<td>SEPA payments</td>
<td>Domestic payments in non-euro currency</td>
<td>International payments</td>
</tr>
</thead>
<tbody>
<tr>
<td>PaymentTypeInformation/ InstructionPriority (payment
level)</td>
<td>"HIGH" for high-priority SCT<br />"NORM" for other SCT<br />Ignored
for SCTInst
</td>
<td>"HIGH" for high-priority CT<br />"NORM" or ignored for
other CT<br>
</td>
<td>"HIGH" for high-priority payments<br />"NORM" or ignored
for other payments<br>
</td>
</tr>
<tr>
<td>PaymentTypeInformation/ ServiceLevel (payment level)</td>
<td>"SEPA" for SCT and SCTInst</td>
<td>ignored</td>
<td>ignored</td>
</tr>
<tr>
<td>PaymentTypeInformation/ CategoryPurpose (payment level)</td>
<td colspan="2">"CASH" for transfer request<br />"DVPM" for
payment request on behalf of a merchant
</td>
<td>"CORT" for generic international payments<br />"INTC" for
transfers between two branches within the same company<br />"TREA"
for treasury transfers
</td>
</tr>
<tr>
<td>PaymentTypeInformation/ LocalInstrument (payment level)</td>
<td>"INST" pour les SCTInst<br />Otherwise ignored
</td>
<td colspan="2">ignored or valued with ISO20022 external code
list values</td>
</tr>
<tr>
<td>RequestedExecutionDate (either at payment or transaction
level)</td>
<td colspan="3">Mandatory (indicates the date on debit on the
ordering party account)</td>
</tr>
<tr>
<td>InstructedAmount (at each transaction level)</td>
<td colspan="3">Mandatory</td>
</tr>
<tr>
<td>ChargeBearer (at each transaction level)</td>
<td>"SLEV" for SCT and SCTInst</td>
<td>"SLEV" or "SHAR"</td>
<td>"CRED", "DEBT" or "SHAR"</td>
</tr>
<tr>
<td>Purpose (at payment level)</td>
<td colspan="3">Optional</td>
</tr>
<tr>
<td>RegulatoryReportingCode (at each transaction level)</td>
<td colspan="2">Not used</td>
<td>Mandatory (possibly multiple values)</td>
</tr>
<tr>
<td>RemittanceInformation</td>
<td colspan="3">Optional<br />Unstructured</td>
</tr>
<tr>
<td>Debtor (at payment level)</td>
<td>Mandatory<br />2 address lines only
</td>
<td colspan="2">Mandatory<br />4 address lines only
</td>
</tr>
<tr>
<td>DebtorAccount (at payment level)</td>
<td>Optional</td>
<td colspan="2">Optional<br />Account currency may be
specified
</td>
</tr>
<tr>
<td>DebtorAgent (at payment level)</td>
<td colspan="3">Optional</td>
</tr>
<tr>
<td>Creditor (either at payment or transaction level)</td>
<td colspan="3">Mandatory<br />2 address lines only
</td>
</tr>
<tr>
<td>CreditorAccount (either at payment or transaction level)</td>
<td>Mandatory</td>
<td colspan="2">Mandatory<br />Account currency may be
specified
</td>
</tr>
<tr>
<td>CreditorAgent (either at payment or transaction level)</td>
<td colspan="3">Optional</td>
</tr>
<tr>
<td>UltimateCreditor (either at payment or transaction level)</td>
<td colspan="3">Optional</td>
</tr>
<tr>
<td>ClearingSystemId et ClearingSystemMemberId (either at
payment or transaction level)</td>
<td colspan="2">Not used</td>
<td>Optional</td>
</tr>
</tbody>
</table>
<br/>
<h4>Prerequisites for all use cases</h4>
<ul>
<li>The TPP has been registered by the Registration Authority for the PISP role</li>
<li>The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).</li>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication </li>
<li>The TPP has presented its "OAUTH2 Client Credential" access token</li>
</ul>
<h4>Business flow</h4>
<h5>Payment Request use case</h5>
The PISP forwards a payment request on behalf of a merchant.<br>
The PSU buys some goods or services on an e-commerce website held by a merchant. Among other payment method, the merchant suggests the use of a PISP service. As there is obviously a contract between the merchant and the PISP, there is no need of such a contract between the PSU and this PISP to initiate the process.<br>
Case of the PSU that chooses to use the PISP service:<br>
<ul>
<li>The merchant forwards the requested payment characteristics to the PISP and redirects the PSU to the PISP portal.</li>
<li>The PISP requests from the PSU which ASPSP will be used.</li>
<li>The PISP prepares the Payment Request and sends this request to the ASPSP.</li>
<li>The Request can embed several payment instructions having different requested execution date.</li>
<li>The beneficiary, as being the merchant, is set at the payment level.</li>
</ul>
<h5>Transfer Request use case</h5>
The PISP forwards a transfer request on behalf of the owner of the account.
<ul>
<li>The PSU provides the PISP with all information needed for the transfer.</li>
<li>The PISP prepares the Transfer Request and sends this request to the relevant ASPSP that holds the debtor account.</li>
<li>The Request can embed several payment instructions having different beneficiaries.</li>
<li>The requested execution date, as being the same for all instructions, is set at the payment level.</li>
</ul>
<h5>Standing Order Request use case</h5>
The PISP forwards a Standing Order request on behalf of the owner of the account.
<ul>
<li>The PSU provides the PISP with all information needed for the Standing Order.</li>
<li>The PISP prepares the Standing Order Request and sends this request to the relevant ASPSP that holds the debtor account.</li>
<li>The Request embeds one single payment instruction with</li>
<ul>
<li>The requested execution date of the first occurrence</li>
<li>The requested execution frequency of the payment in order to compute further execution dates</li>
<li>An execution rule to handle cases when the computed execution dates cannot be processed (e.g. bank holydays)</li>
<li>An optional end date for closing the standing Order</li>
</ul>
</ul>
<h4>Authentication flows for all use cases</h4>
As the request posted by the PISP to the ASPSP needs a PSU authentication before execution, this request will include:
<ul>
<li>The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).</li>
<li>In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process :</li>
<ul>
<li>The first call-back URL will be called by the ASPSP if the Payment Request is processed without any error or rejection by the PSU</li>
<li>The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result.</li>
<li>Both call-back URLS must be used in a TLS-secured request.</li>
</ul>
<li>In case of possible "EMBEDDED" or "DECOUPLED" approaches, the PSU identifier that can be processed by the ASPSP for PSU recognition must have been set within the request body [debtor] structure.</li>
</ul>
The ASPSP saves the request and answers to the PISP. The answer embeds:
<ul>
<li>A location link of the saved Request that will be further used to retrieve the Request and its status information.</li>
<li>The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities.</li>
<li>In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform a authentication.</li>
</ul>
Case of the PSU neither gives nor denies his/her consent, the Request shall expire and is then rejected to the PISP. The expiration delay is specified by each ASPSP.<br>
<h5>Redirect authentication approach </h5>
When the chosen authentication approach within the ASPSP answers is set to "REDIRECT":<br>
<ul>
<li>The PISP redirects the PSU to the ASPSP which authenticates the PSU </li>
<li>The ASPSP asks the PSU to give (or deny) his/her consent to the Payment Request</li>
<li>The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.</li>
<li>The ASPSP is then able to initiate the subsequent Credit Transfer</li>
<li>The ASPSP redirects the PSU to the PISP using one of the call-back URLs provided within the posted Payment Request</li>
</ul>
<img src="https://www.stet.eu//assets/files/documents-api/pisp-redirect-authentication.png" />
<img src="https://www.stet.eu//assets/files/documents-api/pisp-redirect-authentication2.png" />
<h5>Decoupled authentication approach</h5>
When the chosen authentication approach is "DECOUPLED":<br>
<ul>
<li>Based on the PSU identifier provided within the Payment Request by the PISP, the ASPSP gives the PSU with the Payment Request details and challenges the PSU for a Strong Customer Authentication on a decoupled device or application.</li>
<li>The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.</li>
<li>The ASPSP is then able to initiate the subsequent Credit Transfer</li>
<li>The ASPSP notifies the PISP about the finalisation of the authentication and consent process by using one of the call-back URLs provided within the posted Payment Request</li>
</ul>
<img src="https://www.stet.eu//assets/files/documents-api/pisp-decoupled-authentication.png" />
<img src="https://www.stet.eu//assets/files/documents-api/pisp-decoupled-authentication2.png" />
<h5>Embedded authentication approach</h5>
When the chosen authentication approach within the ASPSP answers is set to "EMBEDDED":<br>
<ul>
<li>The TPP informs the PSU that a challenge is needed for completing the Payment Request processing. This challenge will be one of the following:</li>
<ul>
<li>A One-Time-Password sent by the ASPSP to the PSU on a separate device or application.</li>
<li>A response computed by a specific device on base of a challenge sent by the ASPSP to the PSU on a separate device or application.</li>
</ul>
<li>The PSU unlock the device or application through a "knowledge factor" and/or an "inherence factor" (biometric), retrieves the Payment Request details and processes the data sent by the ASPSP; </li>
<li>The PSU might choose or confirm which of his/her accounts shall be used by the ASPSP for the future Credit Transfer when the device or application allows it.</li>
<li>When agreeing the Payment Request, the PSU enters the resulting authentication factor through the PISP interface which will forward it to the ASPSP through a confirmation request (cf. § 4.7)</li>
</ul>
<img src="https://www.stet.eu//assets/files/documents-api/pisp-embedded-authentication.png" />
<img src="https://www.stet.eu//assets/files/documents-api/pisp-embedded-authentication2.png" />
security:
- clientCredentials:
- pisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'201':
description: >-
The request has been created as a resource. The ASPSP must
authenticate the PSU.
headers:
location:
description: >
URI of the created (and updated if needed) Payment Request.
Actually, this link is the URI to be used (cf. § 4.6) for
retrieving the Payment Request ant its status:
- GET /payment-requests/{paymentRequestResourceId}
The parameter {paymentRequestResourceId} is the identifier of
the Payment Request, as the resource that was created on the
ASPSP server side.
schema:
type: string
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
Digest:
description: Digest of the body
schema:
type: string
Signature:
description: >
http-signature of the response (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL
aiming to provide the relevant Qualified Certificate.
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalPaymentRequestCreation'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
requestBody:
$ref: '#/components/requestBodies/PaymentRequestResource'
'/payment-requests/{paymentRequestResourceId}':
get:
operationId: paymentRequestsGet
tags:
- PISP
summary: Retrieval of a payment request (PISP)
description: >
<h3>Description</h3>
The following use cases can be applied:
<ul>
<li>retrieval of a payment request on behalf of a merchant</li>
<li>retrieval of a transfer request on behalf of the account's owner</li>
<li>retrieval of a standing-order request on behalf of the account's owner</li>
</ul>
The PISP has sent a Request through a POST command. <br>
The ASPSP has registered the Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.<br>
The PISP gets the Request that has been updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer.<br>
<h3>Prerequisites</h3>
<ul>
<li>The TPP has been registered by the Registration Authority for the PISP role</li>
<li>The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).</li>
<li>The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)</li>
<ul>
<li>The ASPSP has answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)</li>
</ul>
<li>The TPP and the ASPSP have successfully processed a mutual check and authentication </li>
<li>The TPP has presented its "OAUTH2 Client Credential" access token</li>
</ul>
<h3>Business flow</h3>
The PISP asks to retrieve the Payment/Transfer Request that has been
saved by the ASPSP. The PISP uses the location link provided by the
ASPSP in response of the posting of this request.<br>
The ASPSP returns the previously posted Payment/Transfer Request which
is enriched with:<br>
<ul>
<li>The resource identifiers given by the ASPSP</li>
<li>The status information of the Payment Request and of the subsequent credit transfer</li>
</ul>
The status information must be available during at least 30 calendar
days after the posting of the Payment Request. However, the ASPSP may
increase this availability duration, based on its own rules.<br>
security:
- clientCredentials:
- pisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PaymentRequestResourceIdentification'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: Retrieval of the previously posted Payment Request
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
Digest:
description: Digest of the body
schema:
type: string
Signature:
description: >
http-signature of the response (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL
aiming to provide the relevant Qualified Certificate.
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalPaymentRequest'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
put:
operationId: paymentRequestPut
tags:
- PISP
summary: Modification of a Payment/Transfer Request (PISP)
description: >
<h3>Description</h3>
The PISP sent a Payment/Transfer Request through a POST command.<br>
The ASPSP registered the Payment/Transfer Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.<br>
The PISP got the Payment/Transfer Request that has been updated with the resource identifiers, and eventually the status of the Payment/Transfer Request and the status of the subsequent credit transfer.<br>
The PISP request for the payment cancellation (global cancellation) or for some payment instructions cancellation (partial cancellation)<br>
No other modification of the Payment/Transfer Request is allowed.<br/>
<h3>Prerequisites</h3>
<ul>
<li>The TPP was registered by the Registration Authority for the PISP role</li>
<li>The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).</li>
<li>The TPP previously posted a Payment/Transfer Request which was saved by the ASPSP (cf. § 4.5.3)</li>
<ul>
<li>The ASPSP answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)</li>
<li>The PISP retrieved the saved Payment/Transfer Request (cf. § 4.5.4)</li>
</ul>
<li>The TPP and the ASPSP successfully processed a mutual check and authentication </li>
<li>The TPP presented its "OAUTH2 Client Credential" access token.</li>
<li>The TPP presented the payment/transfer request.</li>
<li>The PSU was successfully authenticated.</li>
</ul>
<h3>Business flow</h3>
the following cases can be applied:
<ul>
<li>Case of a payment with multiple instructions or a standing order, the PISP asks to cancel the whole Payment/Transfer or Standing Order Request including all non-executed payment instructions by setting the [paymentInformationStatus] to "RJCT" and the relevant [statusReasonInformation] to "DS02" at payment level.</li>
<li>Case of a payment with multiple instructions, the PISP asks to cancel one or several payment instructions by setting the [transactionStatus] to "RJCT" and the relevant [statusReasonInformation] to "DS02" at each relevant instruction level.</li>
</ul>
Since the modification request needs a PSU authentication before
committing, the modification request includes:</li>
<ul>
<li>The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).</li>
<li>In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process :</li>
<ul>
<li>The first call-back URL will be called by the ASPSP if the Transfer Request is processed without any error or rejection by the PSU</li>
<li>The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result.</li>
<li>Both call-back URLS must be used in a TLS-secured request.</li>
</ul>
<li>In case of possible "EMBEDDED" or "DECOUPLED" approaches, a PSU identifier that can be processed by the ASPSP for PSU recognition.</li>
</ul>
<li>The ASPSP saves the updated Payment/Transfer Request and answers to the PISP. The answer embeds </li>
<ul>
<li>The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities.</li>
<li>In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform an authentication.</li>
</ul>
</ul>
<h3>Authentication flows for both use cases</h3>
<h4>Redirect authentication approach </h4>
When the chosen authentication approach within the ASPSP answers is set
to "REDIRECT":<br>
<ul>
<li>The PISP redirects the PSU to the ASPSP which authenticates the PSU </li>
<li>The ASPSP asks the PSU to give (or deny) his/her consent to the Payment Request global or partial Cancellation</li>
<li>The ASPSP is then able to initiate the subsequent cancellation</li>
<li>The ASPSP redirects the PSU to the PISP using one of the call-back URLs provided within the posted Payment Request cancellation</li>
</ul>
If the PSU neither gives nor denies his/her consent, the Cancellation
Request shall expire and is then rejected to the PISP. The expiration
delay is specified by each ASPSP.<br>
<h4>Decoupled authentication approach</h4>
When the chosen authentication approach is "DECOUPLED":<br>
<ul>
<li>Based on the PSU identifier provided within the Payment Request by the PISP, the ASPSP provides the PSU with the Cancellation Request details and challenges the PSU for a Strong Customer Authentication on a decoupled device or application.</li>
<li>The PSU confirms or not the Payment Request global or partial Cancellation</li>
<li>The ASPSP is then able to initiate the subsequent cancellation</li>
<li>The ASPSP notifies the PISP about the finalisation of the authentication and cancellation process by using one of the call-back URLs provided within the posted Payment Request</li>
</ul>
If the PSU neither gives nor denies his/her consent, the Cancellation
Request shall expire and is then rejected to the PISP. The expiration
delay is specified by each ASPSP.<br>
<h4>Embedded authentication approach</h4>
When the chosen authentication approach within the ASPSP answers is set
to "EMBEDDED":<br>
<ul>
<li>The TPP informs the PSU that a challenge is needed for completing the Payment Request cancellation processing. This challenge will be one of the following:</li>
<ul>
<li>A One-Time-Password sent by the ASPSP to the PSU on a separate device or application.</li>
<li>A response computed by a specific device on base of a challenge sent by the ASPSP to the PSU on a separate device or application.</li>
</ul>
<li>The PSU unlock the device or application through a "knowledge factor" and/or an "inherence factor" (biometric), retrieves the cancellation details.</li>
<li>The PSU confirms or not the Payment Request global or partial Cancellation</li>
<li>When agreeing the Payment Request cancellation, the PSU enters the resulting authentication factor through the PISP interface which will forward it to the ASPSP through a confirmation request (cf. § 4.7)</li>
</ul>
Case of the PSU neither gives nor denies his/her consent, the
Cancellation Request shall expire and is then rejected to the PISP. The
expiration delay is specified by each ASPSP.<br>
security:
- clientCredentials:
- pisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PaymentRequestResourceIdentification'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: >-
The modification request has been saved. The ASPSP must authenticate
the PSU before committing the update.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
Digest:
description: Digest of the body
schema:
type: string
Signature:
description: >
http-signature of the response (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL
aiming to provide the relevant Qualified Certificate.
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/HalPaymentRequestCreation'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
requestBody:
$ref: '#/components/requestBodies/PaymentRequestResource'
'/payment-requests/{paymentRequestResourceId}/confirmation':
post:
operationId: paymentRequestConfirmationPost
tags:
- PISP
summary: Confirmation of a payment request or a modification request (PISP)
description: |
<h3>Description</h3>
The PISP confirms one of the following requests<br>
<ul>
<li>payment request on behalf of a merchant</li>
<li>transfer request on behalf of the account's owner</li>
<li>standing-order request on behalf of the account's owner</li>
</ul>
The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer.
<h3>Prerequisites</h3>
<ul>
<li> The TPP has been registered by the Registration Authority for the PISP role</li>
<li> The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).</li>
<li> The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)</li>
<ul>
<li>The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4)</li>
<li> The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).</li>
</ul>
<li> The TPP and the ASPSP have successfully processed a mutual check and authentication </li>
<li> The TPP has presented its "OAUTH2 Client Credential" access token </li>
</ul>
<h3>Business flow</h3>
Once the PSU has been authenticated, it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow.<br>
In REDIRECT and DECOUPLED approach, this confirmation is not a prerequisite to the execution of the Credit Transfer.<br>
security:
- clientCredentials:
- pisp
parameters:
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/PaymentRequestResourceIdentification'
- $ref: '#/components/parameters/PsuIpAddressHeader'
- $ref: '#/components/parameters/PsuIpPortHeader'
- $ref: '#/components/parameters/PsuHttpMethodHeader'
- $ref: '#/components/parameters/PsuDateHeader'
- $ref: '#/components/parameters/PsuGeoLocation'
- $ref: '#/components/parameters/PsuUserAgentHeader'
- $ref: '#/components/parameters/PsuRefererHeader'
- $ref: '#/components/parameters/PsuAcceptHeader'
- $ref: '#/components/parameters/PsuAcceptCharsetHeader'
- $ref: '#/components/parameters/PsuAcceptEncodingHeader'
- $ref: '#/components/parameters/PsuAcceptLanguageHeader'
- $ref: '#/components/parameters/PsuDeviceId'
- $ref: '#/components/parameters/DigestHeader'
- $ref: '#/components/parameters/SignatureHeader'
- $ref: '#/components/parameters/Correlation'
responses:
'200':
description: retrieval of the Payment Request enriched with the status report
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
Digest:
description: Digest of the body
schema:
type: string
Signature:
description: >
http-signature of the response (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL
aiming to provide the relevant Qualified Certificate.
schema:
type: string
content:
application/hal+json; charset=utf-8:
schema:
$ref: '#/components/schemas/HalPaymentRequest'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'405':
$ref: '#/components/responses/405'
'406':
$ref: '#/components/responses/406'
'408':
$ref: '#/components/responses/408'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmationResource'
description: >-
parameters needed for confirmation of the Payment Request, especially
in EMBEDDED approach
servers:
- url: /v1
components:
parameters:
AccountResourceIdentification:
name: accountResourceId
in: path
description: Identification of account resource to fetch
required: true
schema:
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
PaymentRequestResourceIdentification:
name: paymentRequestResourceId
in: path
description: Identification of the Payment Request Resource
required: true
schema:
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
AfterEntryReference:
name: afterEntryReference
in: query
description: >
Specifies the value on which the result has to be computed.
Only the transaction having a technical identification greater than this
value must be included within the result
required: false
schema:
type: string
maxLength: 40
ToImputationDate:
name: dateTo
in: query
description: >
Exclusive maximal imputation date of the transactions.
Transactions having an imputation date equal to this parameter are not
included within the result.
required: false
schema:
type: string
format: date-time
FromImputationDate:
name: dateFrom
in: query
description: >
Inclusive minimal imputation date of the transactions.
Transactions having an imputation date equal to this parameter are
included within the result.
required: false
schema:
type: string
format: date-time
AuthorizationParameter:
name: Authorization
in: header
description: Access token to be passed as a header
required: true
schema:
type: string
PsuIpAddressHeader:
name: PSU-IP-Address
in: header
description: IP address used by the PSU's terminal when connecting to the TPP
schema:
type: string
PsuIpPortHeader:
name: PSU-IP-Port
in: header
description: IP port used by the PSU's terminal when connecting to the TPP
schema:
type: string
PsuHttpMethodHeader:
name: PSU-HTTP-Method
in: header
description: Http method for the most relevant PSU’s terminal request to the TTP
schema:
type: string
PsuDateHeader:
name: PSU-Date
in: header
description: Timestamp of the most relevant PSU’s terminal request to the TTP
schema:
type: string
PsuGeoLocation:
name: PSU-GEO-Location
in: header
description: >-
Geographical location of the PSU as provided by the PSU mobile terminal
if any to the TPP
schema:
type: string
PsuUserAgentHeader:
name: PSU-User-Agent
in: header
description: >
"User-Agent" header field sent by the PSU terminal when connecting to
the TPP
schema:
type: string
PsuRefererHeader:
name: PSU-Referer
in: header
description: >
"Referer" header field sent by the PSU terminal when connecting to the
TPP.
Notice that an initial typo in RFC 1945 specifies that "referer"
(incorrect spelling) is to be used. The correct spelling "referrer" can
be used but might not be understood.
schema:
type: string
PsuAcceptHeader:
name: PSU-Accept
in: header
description: >
"Accept" header field sent by the PSU terminal when connecting to the
TPP
schema:
type: string
PsuAcceptCharsetHeader:
name: PSU-Accept-Charset
in: header
description: >
"Accept-Charset" header field sent by the PSU terminal when connecting
to the TPP
schema:
type: string
PsuAcceptEncodingHeader:
name: PSU-Accept-Encoding
in: header
description: >
"Accept-Encoding" header field sent by the PSU terminal when connecting
to the TPP
schema:
type: string
PsuAcceptLanguageHeader:
name: PSU-Accept-Language
in: header
description: >
"Accept-Language" header field sent by the PSU terminal when connecting
to the TPP
schema:
type: string
PsuDeviceId:
name: PSU-Device-ID
in: header
description: >
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 installation identification this ID need to be unaltered
until removal from device.
schema:
type: string
DigestHeader:
name: Digest
in: header
required: false
description: Digest of the body
schema:
type: string
SignatureHeader:
name: Signature
in: header
required: true
description: >
http-signature of the request (cf.
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/)
The keyId must specify the way to get the relevant qualified
certificate. It is requested that this identifier is an URL aiming to
provide the relevant Qualified Certificate.
schema:
type: string
Correlation:
name: X-Request-ID
in: header
required: true
description: >
Correlation header to be set in a request and retrieved in the relevant
response
schema:
type: string
maxLength: 70
responses:
'204':
description: No content.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
'400':
description: Invalid status value
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: 'Unauthorized, authentication failure.'
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'403':
description: >-
Forbidden, authentication successful but access to resource is not
allowed.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: 'Not found, no request available.'
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'405':
description: Method Not Allowed.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'406':
description: Not Acceptable.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'408':
description: Request Timeout.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'409':
description: >
Conflict.
The request could not be completed due to a conflict with the current
state of the target resource.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'429':
description: Too many requests.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'500':
description: Internal server error.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'501':
description: >
Not Implemented.
This code should be used when the entry point is implemented but cannot
provide a result, given the context.
When the entry point is not implemented at all, HTTP400 will be
returned.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
'503':
description: Service unavailable.
headers:
X-Request-ID:
description: >
Correlation header to be set in a request and retrieved in the
relevant response
schema:
type: string
content:
'*/*':
schema:
$ref: '#/components/schemas/ErrorModel'
requestBodies:
PaymentRequestResource:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequestResource'
description: ISO20022 based payment Initiation Request
required: true
securitySchemes:
accessCode:
description: >
In order to access the PSU's account information, the AISP needs to get
either an authorization code grant or a resource owner password OAUTH2
token.
The client_id field within the token request must be filled with the
value of the organization identifier attribute that has been set in the
distinguished name of eIDAS certificate of the TPP, according to ETSI
recommandations.
(cf §5.2.1 of
https://docbox.etsi.org/ESI/Open/Latest_Drafts/ts_119495v000003_for-public-review.pdf)
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://oauth2.aspsp/authorization'
tokenUrl: 'https://oauth2.aspsp/token'
scopes:
aisp: Access by an AISP to one given PSU's account
cbpii: >-
Access by a CBPII to one given PSU's account to check payment
coverage
extended_transaction_history: >-
Access by an AISP to a transaction history over more than the 90
last days
resourceOwnerIdentification:
description: >
In order to access the PSU's account information, the AISP needs to get
either an authorization code grant or a resource owner password OAUTH2
token.
The client_id field within the token request must be filled with the
value of the organization identifier attribute that has been set in the
distinguished name of eIDAS certificate of the TPP, according to ETSI
recommandations.
(cf §5.2.1 of
https://docbox.etsi.org/ESI/Open/Latest_Drafts/ts_119495v000003_for-public-review.pdf)
type: oauth2
flows:
password:
tokenUrl: 'https://oauth2.aspsp/token'
scopes:
aisp: Access by an AISP to one given PSU's account
cbpii: >-
Access by a CBPII to one given PSU's account to check payment
coverage
extended_transaction_history: >-
Access by an AISP to a transaction history over more than the 90
last days
clientCredentials:
description: >
In order to post a Payment or Transfer Request, the PISP needs to get an
client credential OAUTH2 token.
The client_id field within the token request must be filled with the
value of the organization identifier attribute that has been set in the
distinguished name of eIDAS certificate of the TPP, according to ETSI
recommandations.
(cf §5.2.1 of
https://docbox.etsi.org/ESI/Open/Latest_Drafts/ts_119495v000003_for-public-review.pdf)
type: oauth2
flows:
clientCredentials:
tokenUrl: 'https://oauth2.aspsp/token'
scopes:
pisp: Access by a PISP to payments resources
cbpii: >-
Access by a CBPII to one given PSU's account to check payment
coverage
schemas:
ErrorModel:
description: Generic error report structure
type: object
required:
- status
- message
properties:
timestamp:
description: current timestamp
type: string
format: date-time
status:
description: HTTP error code
type: integer
format: int32
error:
description: HTTP error text
type: string
maxLength: 140
message:
description: HTTP textual reason phrase
type: string
maxLength: 140
path:
description: Relevant path that was used
type: string
maxLength: 140
example:
timestamp: '2018-03-30T16:06:27.499+0000'
status: 400
error: Bad Request
message: Missing request header 'Digest' for method parameter of type String
path: /v1/accounts
GenericLink:
x-generic: true
description: hypertext reference
type: object
required:
- href
properties:
href:
description: URI to be used
type: string
maxLength: 140
templated:
description: >-
specifies "true" if href is a URI template, i.e. with parameters.
Otherwise, this property is absent or set to false
type: boolean
example:
href: v1/accounts/Alias1/balances
PsuContextLinks:
description: >
Links that can be used for further navigation when browsing Account
Information at top level
- self: link to the list of all available accounts
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
endUserIdentity:
$ref: '#/components/schemas/GenericLink'
beneficiaries:
$ref: '#/components/schemas/GenericLink'
first:
$ref: '#/components/schemas/GenericLink'
last:
$ref: '#/components/schemas/GenericLink'
next:
$ref: '#/components/schemas/GenericLink'
prev:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/accounts?page=2
first:
href: v1/accounts
last:
href: v1/accounts?page=last
templated: true
next:
href: v1/accounts?page=3
templated: true
prev:
href: v1/accounts
templated: true
AccountLinks:
description: >
links that can be used for further navigation when browsing Account
Information at one account level
- balances: link to the balances of a given account
- transactions: link to the transactions of a given account
type: object
readOnly: true
properties:
balances:
$ref: '#/components/schemas/GenericLink'
transactions:
$ref: '#/components/schemas/GenericLink'
example:
balances:
href: v1/accounts/Alias1/balances-report
transactions:
href: v1/accounts/Alias1/transactions
BalancesLinks:
description: >
links that can be used for further navigation when browsing Account
Information at one account level
- self: link to the balances of a given account
- parent-list: link to the list of all available accounts
- transactions: link to the transactions of a given account
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
parent-list:
$ref: '#/components/schemas/GenericLink'
transactions:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/accounts/Alias1/balances-report
parent-list:
href: v1/accounts
transactions:
href: v1/accounts/Alias1/transactions
TransactionsLinks:
description: >
links that can be used for further navigation when browsing Account
Information at one account level
- self: link to the transactions of a given account
- parent-list: link to the list of all available accounts
- balances: link to the balances of a given account
- first: link to the first page of the transactions result
- last: link to the last page of the transactions result
- next: link to the next page of the transactions result
- prev: link to the previous page of the transactions result
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
parent-list:
$ref: '#/components/schemas/GenericLink'
balances:
$ref: '#/components/schemas/GenericLink'
first:
$ref: '#/components/schemas/GenericLink'
last:
$ref: '#/components/schemas/GenericLink'
next:
$ref: '#/components/schemas/GenericLink'
prev:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/accounts/Alias1/transactions
parent-list:
href: v1/accounts
balances:
href: v1/accounts/Alias1/balances
last:
href: v1/accounts/sAlias1/transactions?page=last
next:
href: v1/accounts/Alias1/transactions?page=3
EndUserIdentityLinks:
description: >
links that can be used for further navigation when browsing Account
Information at one account level
- self: link to the end-user identity
- parent-list: link to the list of all available accounts
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
parent-list:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/end-user-identity
parent-list:
href: v1/accounts
BeneficiariesLinks:
description: >
links that can be used for further navigation when browsing Account
Information at one account level
- self: link to the beneficiaries
- parent-list: link to the list of all available accounts
- first: link to the first page of the beneficiaries result
- last: link to the last page of the beneficiaries result
- next: link to the next page of the beneficiaries result
- prev: link to the previous page of the beneficiaries result
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
parent-list:
$ref: '#/components/schemas/GenericLink'
first:
$ref: '#/components/schemas/GenericLink'
last:
$ref: '#/components/schemas/GenericLink'
next:
$ref: '#/components/schemas/GenericLink'
prev:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/beneficiaries
parent-list:
href: v1/accounts
last:
href: v1/beneficiaries?page=last
next:
href: v1/beneficiaries?page=3
PaymentRequestLinks:
description: >
links that can be used for further navigation when having post a Payment
Request in order to get the relevant status report.
type: object
readOnly: true
properties:
request:
$ref: '#/components/schemas/GenericLink'
description: >
This link provides the payment-request URL for retrieving or
modifying
confirmation:
description: >
This link shall not be provided when the confirmation was already
posted.
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/payment-requests/MyPmtInfRscId
confirmation:
href: v1/payment-requests/MyPmtInfRscId/confirmation
PaymentCoverageReportLinks:
description: >
links that can be used for further navigation to post another coverage
request.
type: object
readOnly: true
required:
- self
properties:
self:
$ref: '#/components/schemas/GenericLink'
example:
self:
href: v1/funds-confirmations
PaymentRequestResourceCreationLinks:
description: >
links that can be used for further navigation, especially in REDIRECT
approach
type: object
readOnly: true
properties:
consentApproval:
$ref: '#/components/schemas/GenericLink'
description: >-
URL to be used by the PISP in order to start the ASPSP
authentication and consent management process
example:
consentApproval:
href: 'https://psd2.aspsp/consent-approval'
AppliedAuthenticationApproach:
description: >
The ASPSP, based on the authentication approaches proposed by the PISP,
choose the one that it can processed, in respect with the preferences
and constraints of the PSU and indicates in this field which approach
has been chosen
type: string
enum:
- REDIRECT
- DECOUPLED
- EMBEDDED
readOnly: true
example: REDIRECT
GenericIdentification:
x-generic: true
description: >
ISO20022: Unique identification of an account, a person or an
organisation, as assigned by an issuer.
API: The ASPSP will document which account reference type it will
support.
type: object
required:
- identification
- schemeName
properties:
identification:
description: |
API: Identifier
type: string
maxLength: 70
schemeName:
description: >
Name of the identification scheme.
Possible values for the scheme name, partially based on ISO20022
external code list, are the following:
- BANK (BankPartyIdentification): Unique and unambiguous assignment
made by a specific bank or similar financial institution to identify
a relationship as defined between the bank and its client.
- COID (CountryIdentificationCode) : Country authority given
organisation identification (e.g., corporate registration number)
- SREN (SIREN): The SIREN number is a 9 digit code assigned by
INSEE, the French National Institute for Statistics and Economic
Studies, to identify an organisation in France.
- SRET (SIRET): The SIRET number is a 14 digit code assigned by
INSEE, the French National Institute for Statistics and Economic
Studies, to identify an organisation unit in France. It consists of
the SIREN number, followed by a five digit classification number, to
identify the local geographical unit of that entity.
- NIDN (NationalIdentityNumber): Number assigned by an authority to
identify the national identity number of a person.
Other values are also permitted, for instance:
- OAUT (OAUTH2): OAUTH2 access token that is owned by the PISP being
also an AISP and that can be used in order to identify the PSU
- CPAN (CardPan): Card PAN
Each implementation of the STET PSD2 API must specify in its own
documentation which schemes can actually been used
type: string
maxLength: 70
issuer:
description: >
ISO20022: Entity that assigns the identification. this could a
country code or any organisation name or identifier that can be
recognized by both parties
type: string
maxLength: 35
example:
identification: 12FR5
schemeName: COID
issuer: FR
AccountIdentification:
x-generic: true
description: >-
Unique and unambiguous identification for the account between the
account owner and the account servicer.
type: object
properties:
iban:
description: >
ISO20022: International Bank Account Number (IBAN) - identification
used internationally by financial institutions to uniquely identify
the account of a customer.
Further specifications of the format and content of the IBAN can be
found in the standard ISO 13616 "Banking and related financial
services - International Bank Account Number (IBAN)" version
1997-10-01, or later revisions.
type: string
pattern: '^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$'
other:
$ref: '#/components/schemas/GenericIdentification'
currency:
description: Currency used for the account
$ref: '#/components/schemas/CurrencyCode'
example:
iban: YY64COJH41059545330222956960771321
CurrencyCode:
description: >
Specifies the currency of the amount or of the account.
A code allocated to a currency by a Maintenance Agency under an
international identification scheme, as described in the latest edition
of the international standard ISO 4217 "Codes for the representation of
currencies and funds".
type: string
pattern: '^[A-Z]{3,3}$'
example: EUR
AmountType:
description: |
Structure aiming to embed the amount and the currency to be used.
type: object
required:
- currency
- amount
properties:
currency:
$ref: '#/components/schemas/CurrencyCode'
amount:
description: >
ISO20022: 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.
type: string
pattern: '^\-{0,1}[0-9]{1,13}(\.[0-9]{0,5}){0,1}$'
example:
currency: EUR
amount: '12.25'
ClearingSystemMemberIdentification:
description: >
ISO20022: Information used to identify a member within a clearing
system.
API: to be used for some specific international credit transfers in
order to identify the beneficiary bank
type: object
properties:
clearingSystemId:
description: >
ISO20022: Specification of a pre-agreed offering between clearing
agents or the channel through which the payment instruction is
processed.
type: string
maxLength: 35
memberId:
description: |
ISO20022: Identification of a member of a clearing system.
type: string
maxLength: 35
example: |
{
"clearingSystemId" : "NZNCC",
"memberId" : "020368"
}
FinancialInstitutionIdentification:
x-generic: true
description: >
ISO20022: Unique and unambiguous identification of a financial
institution, as assigned under an internationally recognised or
proprietary identification scheme.
type: object
required:
- bicFi
properties:
bicFi:
description: >
ISO20022: Code allocated to a financial institution by the ISO 9362
Registration Authority as described in ISO 9362 "Banking - Banking
telecommunication messages - Business identification code (BIC)".
type: string
pattern: '^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$'
clearingSystemMemberId:
$ref: '#/components/schemas/ClearingSystemMemberIdentification'
name:
type: string
description: Name of the financial institution
maxLength: 140
postalAddress:
$ref: '#/components/schemas/PostalAddress'
example:
bicFi: BNKAFRPPXXX
PostalAddress:
description: >
ISO20022 : Information that locates and identifies a specific address,
as defined by postal services.
type: object
required:
- country
- addressLine
properties:
country:
description: >
ISO20022: Country in which a person resides (the place of a person's
home). In the case of a company, it is the country from which the
affairs of that company are directed.
type: string
pattern: '^([A-Z]{2,2})$'
addressLine:
description: |
Unstructured address.
For SEPA payments, only two address lines are allowed.
type: array
maxItems: 2
items:
description: Address line
type: string
maxLength: 70
example:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
PartyIdentification:
x-generic: true
description: >
API : Description of a Party which can be either a person or an
organization.
type: object
required:
- name
properties:
name:
description: >
ISO20022: Name by which a party is known and which is usually used
to identify that party.
type: string
maxLength: 140
postalAddress:
$ref: '#/components/schemas/PostalAddress'
organisationId:
description: Unique and unambiguous way to identify an organisation.
$ref: '#/components/schemas/GenericIdentification'
privateId:
description: Unique and unambiguous identification of a person.
$ref: '#/components/schemas/GenericIdentification'
example:
name: MyPreferedPisp
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
ResourceId:
description: >
API: Identifier assigned by the ASPSP for further use of the created
resource through API calls
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
readOnly: true
example: MyInstrRscId
PaymentIdentification:
description: |
ISO20022: Set of elements used to reference a payment instruction.
type: object
required:
- instructionId
properties:
resourceId:
$ref: '#/components/schemas/ResourceId'
instructionId:
description: >
ISO20022: Unique identification as assigned by an instructing party
for an instructed party to unambiguously identify the instruction.
API: Unique identification shared between the PISP and the ASPSP
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
endToEndId:
description: >
ISO20022: Unique identification assigned by the initiating party to
unambiguously identify the transaction. This identification is
passed on, unchanged, throughout the entire end-to-end chain.
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
example:
resourceId: MyInstrRscId
instructionId: MyInstrId
endToEndId: MyEndToEndId
PriorityCode:
description: >
ISO20022: Indicator of the urgency or order of importance that the
instructing party would like the instructed party to apply to the
processing of the instruction.
API: This field is useless for SCTInst and thus should be ignored.
type: string
enum:
- HIGH
- NORM
example: NORM
CategoryPurposeCode:
description: >
ISO20022: Specifies the high level purpose of the instruction based on a
set of pre-defined categories. This is used by the initiating party to
provide information concerning the processing of the payment. It is
likely to trigger special processing by any of the agents involved in
the payment chain.
API: The following values are allowed:
<table border="1"><tr>
<th>CodeName</th><th>Name</th><th>Definition</th>
</tr><tr>
<td>CASH</td><td>CashManagementTransfer</td><td>Transaction is a general cash management instruction.</td>
</tr><tr>
<td>CORT</td><td>TradeSettlementPayment</td><td>Transaction is related to settlement of a trade, eg a foreign exchange deal or a securities transaction.</td>
</tr><tr>
<td>DVPM</td><td>DeliverAgainstPayment</td><td>Code used to pre-advise the account servicer of a forthcoming deliver against payment instruction.</td>
</tr><tr>
<td>INTC</td><td>IntraCompanyPayment</td><td>Transaction is an intra-company payment, ie, a payment between two companies belonging to the same group.</td>
</tr><tr>
<td>TREA</td><td>TreasuryPayment</td><td>Transaction is related to treasury operations. E.g. financial contract settlement.</td>
</tr></table>
type: string
enum:
- CASH
- CORT
- DVPM
- INTC
- TREA
example: CASH
ServiceLevelCode:
description: >
ISO20022: Agreement under which or rules under which the transaction
should be processed. Specifies a pre-agreed service or level of service
between the parties, as published in an external service level code
list.
API: Only "SEPA" (SEPA Credit Transfer) value is allowed
type: string
enum:
- SEPA
example: SEPA
LocalInstrumentCode:
description: >
ISO20022: User community specific instrument.
Usage: This element is used to specify a local instrument, local
clearing option and/or further qualify the service or service level.
API: "INST" value is to be used in order to ask for an SEPA instant
Payment (SCTInst).
For International payments, this field may be valued with one of the
ISO20022 external code to specify with payment instrument should be used
by the creditor's bank.
type: string
example: INST
PaymentTypeInformation:
description: >
ISO20022: Set of elements used to further specify the type of
transaction.
type: object
properties:
instructionPriority:
$ref: '#/components/schemas/PriorityCode'
serviceLevel:
$ref: '#/components/schemas/ServiceLevelCode'
localInstrument:
$ref: '#/components/schemas/LocalInstrumentCode'
categoryPurpose:
$ref: '#/components/schemas/CategoryPurposeCode'
example:
serviceLevel: SEPA
localInstrument: INST
categoryPurpose: DVPM
PurposeCode:
description: >
ISO20022: Underlying reason for the payment transaction, as published in
an external purpose code list.
API: The following values are allowed for Payment Request
- ACCT (Funds moved between 2 accounts of same account holder at the same bank)
- CASH (general cash management instruction) may be used for Transfer Initiation
- COMC Transaction is related to a payment of commercial credit or debit.
- CPKC General Carpark Charges Transaction is related to carpark charges.
- TRPT Transport RoadPricing Transaction is for the payment to top-up pre-paid card and electronic road pricing for the purpose of transportation
type: string
enum:
- ACCT
- CASH
- COMC
- CPKC
- TRPT
example: CPKC
ChargeBearerCode:
description: >
ISO20022: Specifies which party/parties will bear the charges associated
with the processing of the payment transaction.
The following values are allowed:
<table border="1"><tr>
<th>CodeName</th><th>Name</th><th>Definition</th>
</tr><tr>
<td>DEBT</td><td>BorneByDebtor</td><td>All transaction charges are to be
borne by the debtor.</td>
</tr><tr>
<td>CRED</td><td>BorneByCreditor</td><td>All transaction charges are to
be borne by the creditor.</td>
</tr><tr>
<td>SHAR</td><td>Shared</td><td>In a credit transfer context, means that
transaction charges on the sender side are to be borne by the debtor,
transaction charges on the receiver side are to be borne by the
creditor. In a direct debit context, means that transaction charges on
the sender side are to be borne by the creditor, transaction charges on
the receiver side are to be borne by the debtor.</td>
</tr><tr>
<td>SLEV</td><td>FollowingServiceLevel</td><td>Charges are to be applied
following the rules agreed in the service level and/or scheme.</td>
</tr></table>
type: string
enum:
- DEBT
- CRED
- SHAR
- SLEV
example: SLEV
UnstructuredRemittanceInformation:
description: >
ISO20022: Information supplied to enable the matching of an entry with
the items that the transfer is intended to settle, such as commercial
invoices in an accounts' receivable system.
API: Only one occurrence is allowed
type: array
items:
type: string
description: Relevant information to the transaction
title: remittanceLine
maxLength: 140
example:
- MyRemittanceInformation
PaymentInformationStatusCode:
x-generic: true
description: >
ISO20022: Specifies the status of the payment information.
API: Mandatory. The following values are allowed to provide the status
of the Payment Request
- ACCP (AcceptedCustomerProfile): Preceding check of technical validation was successful. Customer profile check was also successful.
- ACSC (AcceptedSettlementCompleted): Settlement on the debtor's account has been completed.
- ACSP (AcceptedSettlementInProcess): All preceding checks such as technical validation and customer profile were successful. Dynamic risk assessment is now also successful and therefore the Payment Request has been accepted for execution.
- ACTC (AcceptedTechnicalValidation): Authentication and syntactical and semantical validation are successful.
- ACWC (AcceptedWithChange): Instruction is accepted but a change will be made, such as date or remittance not sent.
- ACWP (AcceptedWithoutPosting): Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account.
- PART (PartiallyAccepted): A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status.
- RCVD (Received): Payment initiation has been received by the receiving agent.
- PDNG (Pending): Payment request or individual transaction included in the Payment Request is pending. Further checks and status update will be performed.
- RJCT (Rejected): Payment request has been rejected.
<img src="https://www.stet.eu//assets/files/documents-api/payment-request-status.png" />
type: string
enum:
- ACCP
- ACSC
- ACSP
- ACTC
- ACWC
- ACWP
- PART
- RCVD
- PDNG
- RJCT
example: ACSC
TransactionIndividualStatusCode:
x-generic: true
description: >
ISO20022: Specifies the status of the payment information group.
API: Only the following values are allowed to provide the status of the
subsequent CREDIT TRANSFER to the Payment Request
- RJCT: Payment request or individual transaction included in the
Payment Request has been rejected.
- PDNG: (Pending): Payment request or individual transaction included in
the Payment Request is pending. Further checks and status update will be
performed.
- ACSP: All preceding checks such as technical validation and customer
profile were successful and therefore the Payment Request has been
accepted for execution.
- ACSC: Settlement on the debtor's account has been completed
<img src="https://www.stet.eu//assets/files/documents-api/transaction-status.png" />
type: string
enum:
- RJCT
- PDNG
- ACSP
- ACSC
example: ACSP
StatusReasonInformation:
description: >
ISO20022: Provides detailed information on the status reason.
API: Can only be used in status equal to "RJCT". Only the following
values are allowed:
- AC01 (IncorectAccountNumber): the account number is either invalid or
does not exist
- AC04 (ClosedAccountNumber): the account is closed and cannot be used
- AC06 (BlockedAccount): the account is blocked and cannot be used
- AG01 (Transaction forbidden): Transaction forbidden on this type of
account
- AM18 (InvalidNumberOfTransactions): the number of transactions exceeds
the ASPSP acceptance limit
- CH03 (RequestedExecutionDateOrRequestedCollectionDateTooFarInFuture):
The requested execution date is too far in the future
- CUST (RequestedByCustomer): The reject is due to the debtor: refusal
or lack of liquidity
- DS02 (OrderCancelled): An authorized user has cancelled the order
- FF01 (InvalidFileFormat): The reject is due to the original Payment
Request which is invalid (syntax, structure or values)
- FRAD (FraudulentOriginated): the Payment Request is considered as
fraudulent
- MS03 (NotSpecifiedReasonAgentGenerated): No reason specified by the
ASPSP
- NOAS (NoAnswerFromCustomer): The PSU has neither accepted nor rejected
the Payment Request and a time-out has occurred
- RR01 (MissingDebtorAccountOrIdentification): The Debtor account and/or
Identification are missing or inconsistent
- RR03 (MissingCreditorNameOrAddress): Specification of the creditor’s
name and/or address needed for regulatory requirements is insufficient
or missing.
- RR04 (RegulatoryReason): Reject from regulatory reason
- RR12 (InvalidPartyID): Invalid or missing identification required
within a particular country or payment type.
type: string
enum:
- AC01
- AC04
- AC06
- AG01
- CH03
- CUST
- DS02
- FF01
- FRAD
- MS03
- NOAS
- RR01
- RR03
- RR04
- RR12
example: FRAD
RegulatoryReportingCode:
description: >
Information needed due to regulatory and statutory requirements.
Economical codes to be used are provided by the National Competent
Authority
type: string
maxLength: 10
example: ECO456
RegulatoryReportingCodes:
description: |
List of needed regulatory reporting codes for international payments
type: array
items:
$ref: '#/components/schemas/RegulatoryReportingCode'
minItems: 1
maxItems: 10
example:
- ECO456
- ECO457
RequestedExecutionDate:
description: >
ISO20022: Date at which the initiating party requests the clearing agent
to process the payment.
API:
This field indicates the date at which the debtor account should be
debited.
In most of the cases, especially for international payments, the date of
the credit on the credit account cannot be set. Only SCTInst can
guarantee having the same date for this credit.
This date can be used in the following cases:
- the single requested execution date for a payment having several
instructions. In this case, this field must be set at the payment
level.
- the requested execution date for a given instruction within a payment.
In this case, this field must be set at each instruction level.
- The first date of execution for a standing order.
When the payment cannot be processed at this date, the ASPSP is allowed
to shift the applied execution date to the next possible execution date
for non-standing orders.
For standing orders, the [executionRule] parameter helps to compute the
execution date to be applied.
type: string
format: date-time
example: '2019-02-01T00:00:00.000+01:00'
EndDate:
description: |
The last applicable day of execution for a given standing order.
If not given, the standing order is considered as endless.
type: string
format: date-time
example: '2019-02-01T00:00:00.000+01:00'
ExecutionRule:
description: >
Execution date shifting rule for standing orders
This data attribute defines the behaviour when recurring payment dates
falls on a weekend or bank holiday.
The payment is then executed either the "preceding" or "following"
working day.
ASPSP might reject the request due to the communicated value, if rules
in Online-Banking are not supporting
this execution rule.
- FWNG: following
- PREC: preceding
type: string
enum:
- FWNG
- PREC
example: FWNG
FrequencyCode:
description: >
Frequency rule for standing orders.
The following codes from the "EventFrequency7Code" of ISO 20022 are
supported.
- DAIL: Daily
- WEEK: Weekly
- TOWK: EveryTwoWeeks
- MNTH: Monthly
- TOMN: EveryTwoMonths
- QUTR: Quarterly
- SEMI: SemiAnnual
- YEAR: Annual
However, each ASPSP might restrict these values into a subset if
needed.
type: string
enum:
- DAIL
- WEEK
- TOWK
- MNTH
- TOMN
- QUTR
- SEMI
- YEAR
example: MNTH
CreditTransferTransaction:
description: >
ISO20022: Payment processes required to transfer cash from the debtor to
the creditor.
API:
type: object
required:
- paymentId
- instructedAmount
x-NotAllowedInPost:
- transactionStatus
- statusReasonInformation
properties:
paymentId:
$ref: '#/components/schemas/PaymentIdentification'
requestedExecutionDate:
$ref: '#/components/schemas/RequestedExecutionDate'
endDate:
$ref: '#/components/schemas/EndDate'
executionRule:
$ref: '#/components/schemas/ExecutionRule'
frequency:
$ref: '#/components/schemas/FrequencyCode'
instructedAmount:
$ref: '#/components/schemas/AmountType'
beneficiary:
$ref: '#/components/schemas/Beneficiary'
ultimateCreditor:
$ref: '#/components/schemas/PartyIdentification'
regulatoryReportingCodes:
$ref: '#/components/schemas/RegulatoryReportingCodes'
remittanceInformation:
$ref: '#/components/schemas/UnstructuredRemittanceInformation'
transactionStatus:
$ref: '#/components/schemas/TransactionIndividualStatusCode'
statusReasonInformation:
$ref: '#/components/schemas/StatusReasonInformation'
example:
paymentIdentification:
resourceId: MyInstrRscId
instructionIdentification: MyInstrId
endToEndIdentification: MyEndToEndId
requestedExecutionDate: '2016-12-31T00:00:00.000+01:00'
instructedAmount:
currency: EUR
amount: '124.35'
remittanceInformation:
- MyRemittanceInformation
SupplementaryData:
description: >
ISO20022: Additional information that cannot be captured in the
structured elements and/or any other specific block.
API: This structure is used to embed the relevant URLs for returning the
status report to the PISP and to specify which authentication approaches
are accepted by the PISP and which has been chosen by the ASPSP
type: object
properties:
acceptedAuthenticationApproach:
description: >
can only be set by the PISP
authentication approaches that are supported by the PISP. The PISP
can provide several choices separated by commas.
REDIRECT: the PSU is redirected by the TPP to the ASPSP which
processes identification and authentication
DECOUPLED: the TPP identifies the PSU and forwards the
identification to the ASPSP which processes the authentication
through a decoupled device
EMBEDDED: the TPP identifies the PSU and forwards the identification
to the ASPSP which starts the authentication. The TPP forwards one
authentication factor of the PSU (e.g. OTP or response to a
challenge)
type: array
items:
type: string
description: combination of possible values for authentication approaches
minItems: 1
enum:
- REDIRECT
- DECOUPLED
- EMBEDDED
appliedAuthenticationApproach:
$ref: '#/components/schemas/AppliedAuthenticationApproach'
scaHint:
description: >
can only be set by the PISP
Hint given by the merchant and/or the PISP about an SCA exemption
context
type: string
enum:
- noScaExemption
- scaExemption
successfulReportUrl:
description: >
URL to be used by the ASPSP in order to notify the PISP of the
finalisation of the authentication and consent process in REDIRECT
and DECOUPLED approach
type: string
unsuccessfulReportUrl:
description: >
URL to be used by the ASPSP in order to notify the PISP of the
failure of the authentication and consent process in REDIRECT and
DECOUPLED approach
If this URL is not provided by the PISP, the ASPSP will use the
"successfulReportUrl" even in case of failure of the Payment Request
processing
type: string
example:
successfulReportUrl: 'http://myPisp/PaymentSuccess'
unsuccessfulReportUrl: 'http://myPisp/PaymentFailure'
BalanceStatus:
description: |
Type of balance
- CLBD: (ISO20022 ClosingBooked) Accounting Balance
- XPCD: (ISO20022 Expected) Instant Balance
- VALU: Value-date balance
- OTHR: Other Balance
type: string
enum:
- CLBD
- XPCD
- VALU
- OTHR
example: CLBD
TransactionStatus:
description: |
Type of Transaction
- BOOK: (ISO20022 ClosingBooked) Accounted transaction
- PDNG: (ISO20022 Expected) Instant Balance Transaction
- OTHR: Other
type: string
enum:
- BOOK
- PDNG
- OTHR
example: BOOK
CreditDebitIndicator:
description: |
Accounting flow of the amount
- CRDT: Credit type amount
- DBIT: Debit type amount
type: string
enum:
- CRDT
- DBIT
example: CRDT
Transaction:
description: structure of a transaction
type: object
required:
- transactionAmount
- status
- creditDebitIndicator
- bookingDate
properties:
resourceId:
$ref: '#/components/schemas/ResourceId'
entryReference:
type: string
description: |
Technical incremental identification of the transaction.
maxLength: 40
transactionAmount:
$ref: '#/components/schemas/AmountType'
creditDebitIndicator:
$ref: '#/components/schemas/CreditDebitIndicator'
status:
$ref: '#/components/schemas/TransactionStatus'
bookingDate:
description: >
Booking date of the transaction on the account
If the transaction is not yet booked. This field must be valued with
a scheduled booking date.
type: string
format: date
valueDate:
description: Value date of the transaction on the account
type: string
format: date
transactionDate:
description: |
Date used for specific purposes:
- for card transaction: date of the transaction
- for credit transfer: acquiring date of the transaction
- for direct debit: receiving date of the transaction
type: string
format: date
remittanceInformation:
$ref: '#/components/schemas/UnstructuredRemittanceInformation'
example:
entryReference: AF5T2
transactionAmount:
currency: EUR
amount: '12.25'
creditDebitIndicator: CRDT
status: BOOK
bookingDate: '2018-02-12'
remittanceInformation:
- SEPA CREDIT TRANSFER from PSD2Company
AccountResource:
description: |
PSU account that is made available to the TPP
type: object
required:
- name
- cashAccountType
- _links
properties:
resourceId:
$ref: '#/components/schemas/ResourceId'
bicFi:
description: >
ISO20022: Code allocated to a financial institution by the ISO 9362
Registration Authority as described in ISO 9362 "Banking - Banking
telecommunication messages - Business identification code (BIC)".
type: string
pattern: '^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$'
accountId:
$ref: '#/components/schemas/AccountIdentification'
name:
description: >
Label of the PSU account
In case of a delayed debit card transaction set, the name shall
specify the holder name and the imputation date
type: string
maxLength: 70
details:
description: |
Specifications that might be provided by the ASPSP
- characteristics of the account
- characteristics of the relevant card
type: string
maxLength: 140
linkedAccount:
description: >-
Case of a set of pending card transactions, the APSP will provide
the relevant cash account the card is set up on.
type: string
maxLength: 70
usage:
description: |
Specifies the usage of the account
- PRIV: private personal account
- ORGA: professional account
type: string
enum:
- PRIV
- ORGA
cashAccountType:
description: |
Specifies the type of the account
- CACC: Cash account
- CARD: List of card based transactions
type: string
enum:
- CACC
- CARD
product:
description: |
Product Name of the Bank for this account, proprietary definition
type: string
maxLength: 35
balances:
description: list of balances provided by the ASPSP
type: array
items:
$ref: '#/components/schemas/BalanceResource'
minItems: 1
psuStatus:
description: >-
Relationship between the PSU and the account - Account Holder -
Co-account Holder - Attorney
type: string
maxLength: 35
_links:
$ref: '#/components/schemas/AccountLinks'
example:
resourceId: Alias1
bicFi: BNKAFRPPXXX
name: Compte de Mr et Mme Dupont
usage: PRIV
cashAccountType: CACC
currency: EUR
psuStatus: Co-account Holder
_links:
balances:
href: v1/accounts/Alias1/balances
transactions:
href: v1/accounts/Alias1/transactions
BalanceResource:
description: Structure of an account balance
type: object
required:
- name
- balanceAmount
- balanceType
properties:
name:
description: Label of the balance
type: string
maxLength: 70
balanceAmount:
$ref: '#/components/schemas/AmountType'
balanceType:
$ref: '#/components/schemas/BalanceStatus'
lastChangeDateTime:
description: Timestamp of the last change of the balance amount
type: string
format: date-time
referenceDate:
description: Reference date for the balance
type: string
format: date
lastCommittedTransaction:
description: >
Identification of the last committed transaction. This is actually
useful for instant balance.
type: string
maxLength: 40
example:
name: Solde comptable au 12/01/2017
balanceAmount:
currency: EUR
amount: '123.45'
balanceType: CLBD
lastCommittedTransaction: A452CH
ConfirmationResource:
description: Confirmation request resource
type: object
properties:
psuAuthenticationFactor:
type: string
description: >-
authentication factor forwarded by the TPP to the ASPSP in order to
fulfil the strong customer authentication process
example:
psuAuthenticationFactor: JJKJKJ788GKJKJBK
PaymentInformationId:
description: >
ISO20022 : Reference assigned by a sending party to unambiguously
identify the payment information block within the message.
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
example: MyPmtInfId
CreationDateTime:
description: >
ISO20022: Date and time at which a (group of) payment instruction(s) was
created by the instructing party.
type: string
format: date-time
example: '2018-03-31T13:25:22.527+02:00'
FundsAvailabilityInformation:
description: >
indicator that the payment can be covered or not by the funds available
on the relevant account
- true: payment is covered
- false: payment is not covered
type: boolean
readOnly: true
example: 'true'
BookingInformation:
description: |
indicator that the payment can be immediately booked or not
- true: payment is booked
- false: payment is not booked
type: boolean
readOnly: true
example: 'true'
PaymentRequestResource:
description: >
ISO20022: The PaymentRequestResource message is sent by the Creditor
sending party to the Debtor receiving party, directly or through agents.
It is used by a Creditor to request movement of funds from the debtor
account to a creditor.
API:
Information about the creditor (Id, account and agent) might be placed
either at payment level or at instruction level. Thus multi-beneficiary
payments can be handled.
The requested execution date can be placed either at payment level when
all instructions are requested to be executed at the same date or at
instruction level.
The latest case includes:
- multiple instructions having different requested execution dates
- standing orders settings
type: object
required:
- paymentInformationId
- creationDateTime
- numberOfTransactions
- initiatingParty
- paymentTypeInformation
- creditTransferTransaction
- supplementaryData
x-NotAllowedInPost:
- paymentInformationStatus
- statusReasonInformation
properties:
resourceId:
$ref: '#/components/schemas/ResourceId'
paymentInformationId:
$ref: '#/components/schemas/PaymentInformationId'
creationDateTime:
$ref: '#/components/schemas/CreationDateTime'
numberOfTransactions:
description: >
ISO20022: Number of individual transactions contained in the
message.
API: Each ASPSP will specify a maximum value for this field taking
into accounts its specificities about payment request handling
type: integer
minimum: 1
initiatingParty:
$ref: '#/components/schemas/PartyIdentification'
paymentTypeInformation:
$ref: '#/components/schemas/PaymentTypeInformation'
debtor:
$ref: '#/components/schemas/PartyIdentification'
debtorAccount:
$ref: '#/components/schemas/AccountIdentification'
debtorAgent:
$ref: '#/components/schemas/FinancialInstitutionIdentification'
beneficiary:
$ref: '#/components/schemas/Beneficiary'
ultimateCreditor:
$ref: '#/components/schemas/PartyIdentification'
purpose:
$ref: '#/components/schemas/PurposeCode'
chargeBearer:
$ref: '#/components/schemas/ChargeBearerCode'
paymentInformationStatus:
$ref: '#/components/schemas/PaymentInformationStatusCode'
statusReasonInformation:
$ref: '#/components/schemas/StatusReasonInformation'
fundsAvailability:
$ref: '#/components/schemas/FundsAvailabilityInformation'
booking:
$ref: '#/components/schemas/BookingInformation'
requestedExecutionDate:
description: >
ISO20022: Date at which the initiating party requests the clearing
agent to process the payment.
type: string
format: date-time
creditTransferTransaction:
description: >
ISO20022: Payment processes required to transfer cash from the
debtor to the creditor.
API: Each ASPSP will specify a maxItems value for this field taking
into accounts its specificities about payment request handling
type: array
minItems: 1
items:
$ref: '#/components/schemas/CreditTransferTransaction'
supplementaryData:
$ref: '#/components/schemas/SupplementaryData'
example:
paymentInformationId: MyPmtInfId
creationDateTime: '2018-03-31T13:25:22.527+02:00'
numberOfTransactions: 1
initiatingParty:
name: MyPreferedPisp
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: 12FR5
schemeName: COID
issuer: ACPR
paymentTypeInformation:
serviceLevel: SEPA
localInstrument: INST
categoryPurpose: DVPM
debtor:
name: MyCustomer
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
privateId:
identification: FD37G
schemeName: BANK
issuer: BICXYYTTZZZ
creditor:
name: myMerchant
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: '852126789'
schemeName: SIREN
issuer: FR
creditorAccount:
iban: YY64COJH41059545330222956960771321
ultimateCreditor:
name: myPreferedUltimateMerchant
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: '85212678900025'
schemeName: SIRET
issuer: FR
purpose: COMC
chargeBearer: SLEV
creditTransferTransaction:
- paymentId:
instructionId: MyInstrId
endToEndId: MyEndToEndId
requestedExecutionDate: '2016-12-31T00:00:00.000+01:00'
instructedAmount:
currency: EUR
amount: '124.35'
remittanceInformation:
- MyRemittanceInformation
supplementaryData:
acceptedAuthenticationApproach:
- REDIRECT
- DECOUPLED
successfulReportUrl: 'http://myPisp/PaymentSuccess'
unsuccessfulReportUrl: 'http://myPisp/PaymentFailure'
PaymentCoverageRequestResource:
description: >-
Payment coverage request structure. The request must rely either on a
cash account or a payment card.
type: object
required:
- paymentCoverageRequestId
- instructedAmount
- accountId
properties:
paymentCoverageRequestId:
description: Identification of the payment Coverage Request
type: string
maxLength: 35
payee:
description: The merchant where the card is accepted as information to the PSU.
type: string
maxLength: 70
instructedAmount:
$ref: '#/components/schemas/AmountType'
accountId:
$ref: '#/components/schemas/AccountIdentification'
example:
paymentCoverageRequestId: MyCoverage123456
instructedAmount:
currency: EUR
amount: '12345'
accountId:
iban: YY13RDHN98392489481620896668799742
HalAccounts:
description: >-
HYPERMEDIA structure used for returning the list of the available
accounts to the AISP
type: object
required:
- accounts
- _links
properties:
accounts:
description: |
List of PSU account that are made available to the TPP
type: array
items:
$ref: '#/components/schemas/AccountResource'
_links:
$ref: '#/components/schemas/PsuContextLinks'
example:
accounts:
- resourceId: Alias1
bicFi: BNKAFRPPXXX
name: Compte de Mr et Mme Dupont
usage: PRIV
cashAccountType: CACC
currency: EUR
psuStatus: Co-account Holder
_links:
balances:
href: v1/accounts/Alias1/balances
transactions:
href: v1/accounts/Alias1/transactions
_links:
self:
href: v1/accounts?page=2
first:
href: v1/accounts
last:
href: v1/accounts?page=last
templated: true
next:
href: v1/accounts?page=3
templated: true
prev:
href: v1/accounts
templated: true
HalBalances:
description: >-
HYPERMEDIA structure used for returning the list of the relevant
balances for a given account to the AISP
type: object
required:
- balances
- _links
properties:
balances:
description: List of account balances
type: array
items:
$ref: '#/components/schemas/BalanceResource'
minItems: 1
_links:
$ref: '#/components/schemas/BalancesLinks'
example:
balances:
- name: Solde comptable au 12/01/2017
balanceAmount:
currency: EUR
amount: '123.45'
balanceType: CLBD
lastCommittedTransaction: A452CH
_links:
self:
href: v1/accounts/Alias1/balances-report
parent-list:
href: v1/accounts
transactions:
href: v1/accounts/Alias1/transactions
HalTransactions:
description: >-
HYPERMEDIA structure used for returning the list of the transactions for
a given account to the AISP
type: object
required:
- transactions
- _links
properties:
transactions:
description: List of transactions
type: array
items:
$ref: '#/components/schemas/Transaction'
_links:
$ref: '#/components/schemas/TransactionsLinks'
example:
transactions:
- entryReference: AF5T2
transactionAmount:
currency: EUR
amount: '12.25'
creditDebitIndicator: CRDT
status: BOOK
bookingDate: '2018-02-12'
remittanceInformation:
- SEPA CREDIT TRANSFER from PSD2Company
_links:
self:
href: v1/accounts/Alias1/transactions
parent-list:
href: v1/accounts
balances:
href: v1/accounts/Alias1/balances
last:
href: v1/accounts/sAlias1/transactions?page=last
next:
href: v1/accounts/Alias1/transactions?page=3
HalPaymentRequest:
description: >-
HYPERMEDIA structure used for returning the original Payment Request to
the PISP
type: object
required:
- paymentRequest
- _links
properties:
paymentRequest:
$ref: '#/components/schemas/PaymentRequestResource'
_links:
$ref: '#/components/schemas/PaymentRequestLinks'
example:
paymentRequest:
paymentInformationId: MyPmtInfId
creationDateTime: '2018-03-31T13:25:22.527+02:00'
numberOfTransactions: 1
initiatingParty:
name: MyPreferedPisp
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: 12FR5
schemeName: COID
issuer: ACPR
paymentTypeInformation:
serviceLevel: SEPA
localInstrument: INST
categoryPurpose: DVPM
debtor:
name: MyCustomer
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
privateId:
identification: FD37G
schemeName: BANK
issuer: BICXYYTTZZZ
creditor:
name: myMerchant
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: '852126789'
schemeName: SIREN
issuer: FR
creditorAccount:
iban: YY64COJH41059545330222956960771321
ultimateCreditor:
name: myPreferedUltimateMerchant
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
organisationId:
identification: '85212678900025'
schemeName: SIRET
issuer: FR
purpose: COMC
chargeBearer: SLEV
creditTransferTransaction:
- paymentId:
instructionId: MyInstrId
endToEndId: MyEndToEndId
requestedExecutionDate: '2016-12-31T00:00:00.000+01:00'
instructedAmount:
currency: EUR
amount: '124.35'
remittanceInformation:
- MyRemittanceInformation
supplementaryData:
acceptedAuthenticationApproach:
- REDIRECT
- DECOUPLED
successfulReportUrl: 'http://myPisp/PaymentSuccess'
unsuccessfulReportUrl: 'http://myPisp/PaymentFailure'
_links:
self:
href: v1/payment-requests/MyPmtInfRscId
confirmation:
href: v1/payment-requests/MyPmtInfRscId/confirmation
HalPaymentRequestCreation:
description: >
data forwarded by the ASPSP top the PISP after creation of the Payment
Request resource creation
type: object
properties:
appliedAuthenticationApproach:
$ref: '#/components/schemas/AppliedAuthenticationApproach'
_links:
$ref: '#/components/schemas/PaymentRequestResourceCreationLinks'
example:
appliedAuthenticationApproach:
appliedAuthenticationApproach: REDIRECT
_links:
consentApproval:
href: 'https://psd2.aspsp/consent-approval'
HalPaymentCoverageReport:
description: >-
HYPERMEDIA structure used for returning the payment coverage report to
the CBPII
type: object
required:
- request
- result
- _links
properties:
request:
$ref: '#/components/schemas/PaymentCoverageRequestResource'
result:
description: |
Result of the coverage check :
- true: the payment can be covered
- false: the payment cannot be covered
type: boolean
_links:
$ref: '#/components/schemas/PaymentCoverageReportLinks'
example:
request:
paymentCoverageRequestId: MyCoverage123456
instructedAmount:
currency: EUR
amount: '12345'
accountId:
iban: YY13RDHN98392489481620896668799742
result: true
_links:
self:
href: v1/funds-confirmations
Beneficiary:
description: Specification of a beneficiary
type: object
required:
- creditor
properties:
id:
type: string
description: Id of the beneficiary
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
isTrusted:
description: >
The ASPSP having not implemented the trusted beneficiaries list must
not set this flag.
Otherwise, the ASPSP indicates whether or not the beneficiary has
been registered by the PSU within the trusted beneficiaries list.
- true: the beneficiary is actually a trusted beneficiary
- false: the beneficiary is not a trusted beneficiary
type: boolean
readOnly: true
creditorAgent:
$ref: '#/components/schemas/FinancialInstitutionIdentification'
creditor:
$ref: '#/components/schemas/PartyIdentification'
creditorAccount:
$ref: '#/components/schemas/AccountIdentification'
example:
id: MyBeneficiaryId
isTrusted: true
creditorAgent:
bicFi: BNKAFRPPXXX
creditor:
name: MyPreferedPisp
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
creditorAccount:
iban: YY64COJH41059545330222956960771321
HalEndUserIdentity:
description: HYPERMEDIA structure used for returning the identity of the PSU
type: object
required:
- connectedPsu
- _links
properties:
connectedPsu:
description: >
Last name and first name that has granted access to the AISP on the
accounts data
This information can be retrieved based on the PSU's authentication
that occurred during the OAUTH2 access token initialisation.
type: string
maxLength: 70
_links:
$ref: '#/components/schemas/EndUserIdentityLinks'
example:
connectedPsu: IMeMyself
_links:
self:
href: v1/end-user-identity
parent-list:
href: v1/accounts
HalBeneficiaries:
description: >-
HYPERMEDIA structure used for returning the list of the whitelisted
beneficiaries
type: object
required:
- beneficiaries
- _links
properties:
beneficiaries:
type: array
description: List of trusted beneficiaries
items:
$ref: '#/components/schemas/Beneficiary'
_links:
$ref: '#/components/schemas/BeneficiariesLinks'
example:
beneficiaries:
- id: MyBeneficiaryId
isTrusted: true
creditorAgent:
bicFi: BNKAFRPPXXX
creditor:
name: MyPreferedPisp
postalAddress:
country: FR
addressLine:
- 18 rue de la DSP2
- 75008 PARIS
creditorAccount:
iban: YY64COJH41059545330222956960771321
_links:
self:
href: v1/beneficiaries
parent-list:
href: v1/accounts
last:
href: v1/beneficiaries?page=last
next:
href: v1/beneficiaries?page=3
AccessibleAccounts:
description: List of accessible accounts for one given functionality
type: array
items:
$ref: '#/components/schemas/AccountIdentification'
example:
- iban: YY64COJH41059545330222956960771321
Access:
description: Requested access services.
type: object
required:
- balances
- transactions
- trustedBeneficiaries
- psuIdentity
properties:
balances:
$ref: '#/components/schemas/AccessibleAccounts'
transactions:
$ref: '#/components/schemas/AccessibleAccounts'
trustedBeneficiaries:
description: >
Indicator that access to the trusted beneficiaries list was granted
or not to the AISP by the PSU
- true: the access was granted
- false: the access was not granted
type: boolean
psuIdentity:
description: >
Indicator that access to the PSU identity, first name and last name,
was granted or not to the AISP by the PSU
- true: the access was granted
- false: the access was not granted
type: boolean
example:
balances:
- iban: YY64COJH41059545330222956960771321
trustedBeneficiaries: true
psuIdentity: true
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment