API Explorer

STET

AISP
CBPII
- Payment coverage check request (CBPII)
PISP

STET v1.4 (11 APIs)

API Host: https://api.openbankproject.com

Bank

Accounts

Views

Counterparties

Transactions

Forwarding the PSU consent (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

In the mixed detailed consent on accounts

the AISP captures the consent of the PSU
then it forwards this consent to the ASPSP

This consent replaces any prior consent that was previously sent by the AISP.

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role.
The TPP and the PSU have a contract that has been enrolled by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

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.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by consentsPut

Retrieval of an account balances report (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role
The TPP and the PSU have a contract that has been enrolled by the ASPSP
At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The TPP has previously retrieved the list of available accounts for the PSU

Business flow

The AISP requests the ASPSP on one of the PSU's accounts.
The ASPSP answers by providing a list of balances on this account.

The ASPSP must provide at least the accounting balance on the account.
The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
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.

Typical Successful Response:

								
									{
  "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"
    }
  }
}

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by accountsBalancesGet

Retrieval of an account transaction set (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

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

on a given imputation date range
past a given incremental technical identification

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.

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role
The TPP and the PSU have a contract that has been enrolled by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
The TPP has previously retrieved the list of available accounts for the PSU

Business flow

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.

Typical Successful Response:

								
									{
  "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"
    }
  }
}

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by accountsTransactionsGet

Retrieval of the PSU accounts (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

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.

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role.
The TPP and the PSU have a contract that has been enrolled by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow

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.

Typical Successful Response:

								
									{
  "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
    }
  }
}

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by accountsGet

Retrieval of the identity of the end-user (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

This call returns the identity of the PSU (end-user).

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role.
The TPP and the PSU have a contract that has been enrolled by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow

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.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by endUserIdentityGet

Retrieval of the trusted beneficiaries list (AISP)

NOTE: This endpoint currently only returns example data.

        ### Description

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.

Prerequisites

The TPP has been registered by the Registration Authority for the AISP role.
The TPP and the PSU have a contract that has been enrolled by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.
The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.

Business Flow

The AISP asks for the trusted beneficiaries list. The ASPSP answers with a list of beneficiary details structure.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by trustedBeneficiariesGet

Payment coverage check request (CBPII)

NOTE: This endpoint currently only returns example data.

        ### Description

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.

Prerequisites

The TPP has been registered by the Registration Authority for the CBPII role
The TPP and the PSU have a contract that has been registered by the ASPSP
The TPP and the ASPSP have successfully processed a mutual check and authentication
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.

Business flow

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.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by fundsConfirmationsPost

Confirmation of a payment request or a modification request (PISP)

NOTE: This endpoint currently only returns example data.

        ### Description

The PISP confirms one of the following requests

payment request on behalf of a merchant
transfer request on behalf of the account's owner
standing-order request on behalf of the account's owner

The ASPSP answers with a status of the relevant request and the subsequent Credit Transfer.

Prerequisites

The TPP has been registered by the Registration Authority for the PISP role
The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)
The TPP and the ASPSP have successfully processed a mutual check and authentication
The TPP has presented its "OAUTH2 Client Credential" access token

Business flow

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.
In REDIRECT and DECOUPLED approach, this confirmation is not a prerequisite to the execution of the Credit Transfer.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by paymentRequestConfirmationPost

Modification of a Payment/Transfer Request (PISP)

NOTE: This endpoint currently only returns example data.

        ### Description

The PISP sent a Payment/Transfer Request through a POST command.
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.
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.
The PISP request for the payment cancellation (global cancellation) or for some payment instructions cancellation (partial cancellation)
No other modification of the Payment/Transfer Request is allowed.

Prerequisites

The TPP was registered by the Registration Authority for the PISP role
The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
The TPP previously posted a Payment/Transfer Request which was saved by the ASPSP (cf. § 4.5.3)
The TPP and the ASPSP successfully processed a mutual check and authentication
The TPP presented its "OAUTH2 Client Credential" access token.
The TPP presented the payment/transfer request.
The PSU was successfully authenticated.

Business flow

the following cases can be applied:

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

Since the modification request needs a PSU authentication before committing, the modification request includes:

The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).
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 :
In case of possible "EMBEDDED" or "DECOUPLED" approaches, a PSU identifier that can be processed by the ASPSP for PSU recognition.
The ASPSP saves the updated Payment/Transfer Request and answers to the PISP. The answer embeds

Typical Successful Response:

								
									{
  "appliedAuthenticationApproach":{
    "appliedAuthenticationApproach":"REDIRECT"
  },
  "_links":{
    "consentApproval":{
      "href":"https://psd2.aspsp/consent-approval"
    }
  }
}

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by paymentRequestPut

Payment request initiation (PISP)

NOTE: This endpoint currently only returns example data.

        ### Description

The following use cases can be applied:

payment request on behalf of a merchant
transfer request on behalf of the account's owner
standing-order request on behalf of the account's owner

Data content

A payment request or a transfer request might embed several payment instructions having

one single execution date or multiple execution dates
one single beneficiary or multiple beneficiaries

Having at the same time multiple beneficiaries and multiple execution date might not be a relevant business case, although it is technically allowed.
Each implementation will have to specify which business use cases are actually supported.
A standing order request must embed one single payment instruction and must address one single beneficiary.

The beneficiary must be set at the payment level
The standing order specific characteristics (start date, periodicity...) must be set at the instruction level

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:

                                  Structure                                      |                             SEPA payments                             |           Domestic payments in non-euro currency           |                                                          International payments                                                           |

PaymentTypeInformation/ InstructionPriority (payment level)	"HIGH" for high-priority SCT "NORM" for other SCT Ignored for SCTInst	"HIGH" for high-priority CT "NORM" or ignored for other CT	"HIGH" for high-priority payments "NORM" or ignored for other payments
PaymentTypeInformation/ ServiceLevel (payment level)	"SEPA" for SCT and SCTInst	ignored	ignored
PaymentTypeInformation/ CategoryPurpose (payment level)	"CASH" for transfer request "DVPM" for payment request on behalf of a merchant		"CORT" for generic international payments "INTC" for transfers between two branches within the same company "TREA" for treasury transfers
PaymentTypeInformation/ LocalInstrument (payment level)	"INST" pour les SCTInst Otherwise ignored	ignored or valued with ISO20022 external code list values
RequestedExecutionDate (either at payment or transaction level)	Mandatory (indicates the date on debit on the ordering party account)
InstructedAmount (at each transaction level)	Mandatory
ChargeBearer (at each transaction level)	"SLEV" for SCT and SCTInst	"SLEV" or "SHAR"	"CRED", "DEBT" or "SHAR"
Purpose (at payment level)	Optional
RegulatoryReportingCode (at each transaction level)	Not used		Mandatory (possibly multiple values)
RemittanceInformation	Optional Unstructured
Debtor (at payment level)	Mandatory 2 address lines only	Mandatory 4 address lines only
DebtorAccount (at payment level)	Optional	Optional Account currency may be specified
DebtorAgent (at payment level)	Optional
Creditor (either at payment or transaction level)	Mandatory 2 address lines only
CreditorAccount (either at payment or transaction level)	Mandatory	Mandatory Account currency may be specified
CreditorAgent (either at payment or transaction level)	Optional
UltimateCreditor (either at payment or transaction level)	Optional
ClearingSystemId et ClearingSystemMemberId (either at payment or transaction level)	Not used		Optional

Prerequisites for all use cases

The TPP has been registered by the Registration Authority for the PISP role
The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
The TPP and the ASPSP have successfully processed a mutual check and authentication
The TPP has presented its "OAUTH2 Client Credential" access token

Business flow

Payment Request use case

The PISP forwards a payment request on behalf of a merchant.
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.
Case of the PSU that chooses to use the PISP service:

The merchant forwards the requested payment characteristics to the PISP and redirects the PSU to the PISP portal.
The PISP requests from the PSU which ASPSP will be used.
The PISP prepares the Payment Request and sends this request to the ASPSP.
The Request can embed several payment instructions having different requested execution date.
The beneficiary, as being the merchant, is set at the payment level.

Transfer Request use case

The PISP forwards a transfer request on behalf of the owner of the account.

The PSU provides the PISP with all information needed for the transfer.
The PISP prepares the Transfer Request and sends this request to the relevant ASPSP that holds the debtor account.
The Request can embed several payment instructions having different beneficiaries.
The requested execution date, as being the same for all instructions, is set at the payment level.

Standing Order Request use case

The PISP forwards a Standing Order request on behalf of the owner of the account.

The PSU provides the PISP with all information needed for the Standing Order.
The PISP prepares the Standing Order Request and sends this request to the relevant ASPSP that holds the debtor account.
The Request embeds one single payment instruction with

Authentication flows for all use cases

As the request posted by the PISP to the ASPSP needs a PSU authentication before execution, this request will include:

The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).
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 :
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.

The ASPSP saves the request and answers to the PISP. The answer embeds:

A location link of the saved Request that will be further used to retrieve the Request and its status information.
The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities.
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.

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.

Redirect authentication approach

When the chosen authentication approach within the ASPSP answers is set to "REDIRECT":

The PISP redirects the PSU to the ASPSP which authenticates the PSU
The ASPSP asks the PSU to give (or deny) his/her consent to the Payment Request
The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
The ASPSP is then able to initiate the subsequent Credit Transfer
The ASPSP redirects the PSU to the PISP using one of the call-back URLs provided within the posted Payment Request

Decoupled authentication approach

When the chosen authentication approach is "DECOUPLED":

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.
The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
The ASPSP is then able to initiate the subsequent Credit Transfer
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

Embedded authentication approach

When the chosen authentication approach within the ASPSP answers is set to "EMBEDDED":

The TPP informs the PSU that a challenge is needed for completing the Payment Request processing. This challenge will be one of the following:
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;
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.
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)

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by paymentRequestsPost

Retrieval of a payment request (PISP)

NOTE: This endpoint currently only returns example data.

        ### Description

The following use cases can be applied:

retrieval of a payment request on behalf of a merchant
retrieval of a transfer request on behalf of the account's owner
retrieval of a standing-order request on behalf of the account's owner

The PISP has sent a Request through a POST command.
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.
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.

Prerequisites

The TPP has been registered by the Registration Authority for the PISP role
The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)
The TPP and the ASPSP have successfully processed a mutual check and authentication
The TPP has presented its "OAUTH2 Client Credential" access token

Business flow

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.
The ASPSP returns the previously posted Payment/Transfer Request which is enriched with:

The resource identifiers given by the ASPSP
The status information of the Payment Request and of the subsequent credit transfer

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.

Typical Successful Response:

Headers:

Required Roles:

Possible Errors:

OBP-20001: User not logged in. Authentication is required!
OBP-50000: Unknown Error.

Implemented in STETv1.4 by paymentRequestsGet

Featured APIs

STET

STET v1.4 (11 APIs)

Bank

Accounts

Views

Counterparties

Transactions

Forwarding the PSU consent (AISP)

Retrieval of an account balances report (AISP)

Retrieval of an account transaction set (AISP)

Retrieval of the PSU accounts (AISP)

Retrieval of the identity of the end-user (AISP)

Retrieval of the trusted beneficiaries list (AISP)

Payment coverage check request (CBPII)

Confirmation of a payment request or a modification request (PISP)

Modification of a Payment/Transfer Request (PISP)

Payment request initiation (PISP)

Retrieval of a payment request (PISP)