| 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 | |
security:
- clientCredentials:
- pisp
parameters:
- $ref: "#/parameters/AuthorizationParameter"
- $ref: "#/parameters/PaymentRequest"
- $ref: "#/parameters/PsuIpAddressHeader"
- $ref: "#/parameters/PsuIpPortHeader"
- $ref: "#/parameters/PsuHttpMethodHeader"
- $ref: "#/parameters/PsuDateHeader"
- $ref: "#/parameters/PsuGeoLocation"
- $ref: "#/parameters/PsuUserAgentHeader"
- $ref: "#/parameters/PsuRefererHeader"
- $ref: "#/parameters/PsuAcceptHeader"
- $ref: "#/parameters/PsuAcceptCharsetHeader"
- $ref: "#/parameters/PsuAcceptEncodingHeader"
- $ref: "#/parameters/PsuAcceptLanguageHeader"
- $ref: "#/parameters/PsuDeviceId"
- $ref: "#/parameters/DigestHeader"
- $ref: "#/parameters/SignatureHeader"
- $ref: "#/parameters/Correlation"
responses:
"201":
description: The request has been created as a resource. The ASPSP must authenticate the PSU.
schema:
$ref: "#/definitions/HalPaymentRequestCreation"
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.
type: string
X-Request-ID:
type: string
description: |
Correlation header to be set in a request and retrieved in the relevant response
Digest:
type: string
description: Digest of the body
Signature:
type: string
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.
"400":
$ref: "#/responses/400"
"401":
$ref: "#/responses/401"
"403":
$ref: "#/responses/403"
"405":
$ref: "#/responses/405"
"406":
$ref: "#/responses/406"
"408":
$ref: "#/responses/408"
"429":
$ref: "#/responses/429"
"500":
$ref: "#/responses/500"
"503":
$ref: "#/responses/503"
/payment-requests/{paymentRequestResourceId}:
get:
operationId: paymentRequestsGet
tags:
- PISP
produces:
- application/hal+json; charset=utf-8
summary: Retrieval of a payment request (PISP)
description: |
| CodeName | Name | Definition |
|---|---|---|
| CASH | CashManagementTransfer | Transaction is a general cash management instruction. |
| CORT | TradeSettlementPayment | Transaction is related to settlement of a trade, eg a foreign exchange deal or a securities transaction. |
| DVPM | DeliverAgainstPayment | Code used to pre-advise the account servicer of a forthcoming deliver against payment instruction. |
| INTC | IntraCompanyPayment | Transaction is an intra-company payment, ie, a payment between two companies belonging to the same group. |
| TREA | TreasuryPayment | Transaction is related to treasury operations. E.g. financial contract settlement. |
| CodeName | Name | Definition |
|---|---|---|
| DEBT | BorneByDebtor | All transaction charges are to be borne by the debtor. |
| CRED | BorneByCreditor | All transaction charges are to be borne by the creditor. |
| SHAR | Shared | 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. |
| SLEV | FollowingServiceLevel | Charges are to be applied following the rules agreed in the service level and/or scheme. |
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. In the case of SCTInst, this status must not been set by the debtor's Bank before the reception of the positive confirmation.
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: "#/definitions/RegulatoryReportingCode"
minItems: 1
maxItems: 10
example: ["ECO456", "ECO457"]
### Modified for CR262: Add a precision on RequestedExecutionDate
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
### Fixed on making remittanceInformùmation as optional
required:
- paymentId
- instructedAmount
x-not-allowed-in-post:
- transactionStatus
- statusReasonInformation
properties:
paymentId:
$ref: "#/definitions/PaymentIdentification"
requestedExecutionDate:
$ref: "#/definitions/RequestedExecutionDate"
endDate:
$ref: "#/definitions/EndDate"
executionRule:
$ref: "#/definitions/ExecutionRule"
frequency:
$ref: "#/definitions/FrequencyCode"
instructedAmount:
$ref: "#/definitions/AmountType"
beneficiary:
$ref: "#/definitions/Beneficiary"
ultimateCreditor:
$ref: "#/definitions/PartyIdentification"
regulatoryReportingCodes:
$ref: "#/definitions/RegulatoryReportingCodes"
remittanceInformation:
$ref: "#/definitions/UnstructuredRemittanceInformation"
transactionStatus:
$ref: "#/definitions/TransactionIndividualStatusCode"
statusReasonInformation:
$ref: "#/definitions/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"],
}
### Modified for CR233: Check the cardinality of "acceptedAuthenticationApproach"
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: "#/definitions/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"
### Modified for CR274: Add precision on bookingDate
Transaction:
description: structure of a transaction
type: object
### Fixed on making remittanceInformùmation as optional
required:
- transactionAmount
- status
- creditDebitIndicator
- bookingDate
properties:
resourceId:
$ref: "#/definitions/ResourceId"
entryReference:
type: string
description: |
Technical incremental identification of the transaction.
maxLength: 40
transactionAmount:
$ref: "#/definitions/AmountType"
creditDebitIndicator:
$ref: "#/definitions/CreditDebitIndicator"
status:
$ref: "#/definitions/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: "#/definitions/UnstructuredRemittanceInformation"
example:
{
"entryReference": "AF5T2",
"transactionAmount": { "currency": "EUR", "amount": "12.25" },
"creditDebitIndicator": "CRDT",
"status": "BOOK",
"bookingDate": "2018-02-12",
"remittanceInformation": ["SEPA CREDIT TRANSFER from PSD2Company"],
}
# API resources definitions
### Modified for CR226: Add a currency code in order to specify a multicurrency account
AccountResource:
description: |
PSU account that is made available to the TPP
type: object
required:
- name
- cashAccountType
- _links
properties:
resourceId:
$ref: "#/definitions/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: "#/definitions/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 ASPSP 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: "#/definitions/BalanceResource"
minItems: 1
psuStatus:
description: Relationship between the PSU and the account
- Account Holder
- Co-account Holder
- Attorney
type: string
maxLength: 35
_links:
$ref: "#/definitions/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: "#/definitions/AmountType"
balanceType:
$ref: "#/definitions/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-not-allowed-in-post:
- paymentInformationStatus
- statusReasonInformation
properties:
resourceId:
$ref: "#/definitions/ResourceId"
paymentInformationId:
$ref: "#/definitions/PaymentInformationId"
creationDateTime:
$ref: "#/definitions/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: "#/definitions/PartyIdentification"
paymentTypeInformation:
$ref: "#/definitions/PaymentTypeInformation"
debtor:
$ref: "#/definitions/PartyIdentification"
debtorAccount:
$ref: "#/definitions/AccountIdentification"
debtorAgent:
$ref: "#/definitions/FinancialInstitutionIdentification"
beneficiary:
$ref: "#/definitions/Beneficiary"
ultimateCreditor:
$ref: "#/definitions/PartyIdentification"
purpose:
$ref: "#/definitions/PurposeCode"
chargeBearer:
$ref: "#/definitions/ChargeBearerCode"
paymentInformationStatus:
$ref: "#/definitions/PaymentInformationStatusCode"
statusReasonInformation:
$ref: "#/definitions/StatusReasonInformation"
fundsAvailability:
$ref: "#/definitions/FundsAvailabilityInformation"
booking:
$ref: "#/definitions/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: "#/definitions/CreditTransferTransaction"
supplementaryData:
$ref: "#/definitions/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: "#/definitions/AmountType"
accountId:
$ref: "#/definitions/AccountIdentification"
example:
{
"paymentCoverageRequestId": "MyCoverage123456",
"instructedAmount": { "currency": "EUR", "amount": "12345" },
"accountId": { "iban": "YY13RDHN98392489481620896668799742" },
}
# API HAL definitions
### Modified for CR230: Clarify the behaviour about communicating the PSU identity
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: "#/definitions/AccountResource"
_links:
$ref: "#/definitions/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: "#/definitions/BalanceResource"
minItems: 1
_links:
$ref: "#/definitions/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: "#/definitions/Transaction"
_links:
$ref: "#/definitions/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: "#/definitions/PaymentRequestResource"
_links:
$ref: "#/definitions/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: "#/definitions/AppliedAuthenticationApproach"
_links:
$ref: "#/definitions/PaymentRequestResourceCreationLinks"
example:
{
"appliedAuthenticationApproach":
{ "appliedAuthenticationApproach": "REDIRECT" },
"_links":
{
"consentApproval":
{ "href": "https://psd2.aspsp/consent-approval" },
},
}
### Modified for CR234: Replace PIISP by CBPII (Card Based Payment Instrument Issuers)
HalPaymentCoverageReport:
description: HYPERMEDIA structure used for returning the payment coverage report to the CBPII
type: object
required:
- request
- result
- _links
properties:
request:
$ref: "#/definitions/PaymentCoverageRequestResource"
result:
description: |
Result of the coverage check :
- true: the payment can be covered
- false: the payment cannot be covered
type: boolean
_links:
$ref: "#/definitions/PaymentCoverageReportLinks"
example:
{
"request":
{
"paymentCoverageRequestId": "MyCoverage123456",
"instructedAmount": { "currency": "EUR", "amount": "12345" },
"accountId": { "iban": "YY13RDHN98392489481620896668799742" },
},
"result": true,
"_links": { "self": { "href": "v1/funds-confirmations" } },
}
### Modified for CR231: Clarification about "istrusted" set to false by the PISP
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})$'
### Fixed on useless comment
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: "#/definitions/FinancialInstitutionIdentification"
creditor:
$ref: "#/definitions/PartyIdentification"
creditorAccount:
$ref: "#/definitions/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" },
}
### Added for CR230: Clarify the behaviour about communicating the PSU identity
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: "#/definitions/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: "#/definitions/Beneficiary"
_links:
$ref: "#/definitions/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: "#/definitions/AccountIdentification"
example: [{ "iban": "YY64COJH41059545330222956960771321" }]
Access:
description: Requested access services.
type: object
required:
- balances
- transactions
- trustedBeneficiaries
- psuIdentity
properties:
balances:
$ref: "#/definitions/AccessibleAccounts"
transactions:
$ref: "#/definitions/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,
}
parameters:
# Path parameters
AccountResourceIdentification:
name: accountResourceId
in: path
description: Identification of account resource to fetch
required: true
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
PaymentRequestResourceIdentification:
name: paymentRequestResourceId
in: path
description: Identification of the Payment Request Resource
required: true
type: string
pattern: '^([a-zA-Z0-9 /\-?:\()\.,'']{1,35})$'
# Query parameters
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
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
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
type: string
format: date-time
# Header parameters
AuthorizationParameter:
name: Authorization
in: header
description: Access token to be passed as a header
required: true
type: string
PsuIpAddressHeader:
name: PSU-IP-Address
type: string
in: header
description: IP address used by the PSU's terminal when connecting to the TPP
PsuIpPortHeader:
name: PSU-IP-Port
type: string
in: header
description: IP port used by the PSU's terminal when connecting to the TPP
PsuHttpMethodHeader:
name: PSU-HTTP-Method
type: string
in: header
description: Http method for the most relevant PSU’s terminal request to the TTP
PsuDateHeader:
name: PSU-Date
type: string
in: header
description: Timestamp of the most relevant PSU’s terminal request to the TTP
PsuGeoLocation:
name: PSU-GEO-Location
type: string
in: header
description: Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP
PsuUserAgentHeader:
name: PSU-User-Agent
type: string
in: header
description: |
"User-Agent" header field sent by the PSU terminal when connecting to the TPP
PsuRefererHeader:
name: PSU-Referer
type: string
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.
PsuAcceptHeader:
name: PSU-Accept
type: string
in: header
description: |
"Accept" header field sent by the PSU terminal when connecting to the TPP
PsuAcceptCharsetHeader:
name: PSU-Accept-Charset
type: string
in: header
description: |
"Accept-Charset" header field sent by the PSU terminal when connecting to the TPP
PsuAcceptEncodingHeader:
name: PSU-Accept-Encoding
type: string
in: header
description: |
"Accept-Encoding" header field sent by the PSU terminal when connecting to the TPP
PsuAcceptLanguageHeader:
name: PSU-Accept-Language
type: string
in: header
description: |
"Accept-Language" header field sent by the PSU terminal when connecting to the TPP
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.
type: string
DigestHeader:
name: Digest
type: string
in: header
required: false
description: Digest of the body
SignatureHeader:
name: Signature
type: string
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.
Correlation:
name: X-Request-ID
type: string
maxLength: 70
in: header
required: true
description: |
Correlation header to be set in a request and retrieved in the relevant response
# body parameters
PaymentRequest:
name: paymentRequest
in: body
description: ISO20022 based payment Initiation Request
required: true
schema:
$ref: "#/definitions/PaymentRequestResource"
Confirmation:
name: confirmationRequest
in: body
description: parameters needed for confirmation of the Payment Request, especially in EMBEDDED approach
schema:
$ref: "#/definitions/ConfirmationResource"
PaymentCoverageRequest:
name: paymentCoverage
in: body
description: parameters of a payment coverage request
required: true
schema:
$ref: "#/definitions/PaymentCoverageRequestResource"
Consents:
name: access
in: body
description: List of consents granted to the AISP by the PSU.
schema:
$ref: "#/definitions/Access"