Paths
/{payment-service}/{payment-product}/{paymentId}/status
Payment initiation status request
Check the transaction status of a payment initiation.
{
"enum": [
"payments",
"periodic-payments",
"bulk-payments"
]
}{
"enum": [
"domestic",
"sepa-credit-transfers",
"cross-border-credit-transfers",
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"domestic-credit-transfers-hr",
"hr-rtgs-payments",
"target-2-payments",
"pain001-credit-transfers-hr"
]
}ID of the request, unique to the call, as determined by the initiating party.
Is contained if and only if the "Signature" element is contained in the header of the request.
A signature of the request by the TPP on application level. This might be mandated by ASPSP.
The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples
- Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)"
- iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0"
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Conflict
Unsuported Media Type
Too Many Requests
Internal Server Error
Service Unavailable
/payments/{payment-product}/{paymentId}
Get Payment Information
Returns the content of a payment object.
{
"enum": [
"domestic",
"sepa-credit-transfers",
"cross-border-credit-transfers",
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"domestic-credit-transfers-hr",
"hr-rtgs-payments",
"target-2-payments"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
Is contained if and only if the "Signature" element is contained in the header of the request.
A signature of the request by the TPP on application level. This might be mandated by ASPSP.
The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples
- Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)"
- iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0"
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Conflict
Unsuported Media Type
Too Many Requests
Internal Server Error
Service Unavailable
/periodic-payments/{payment-product}/{paymentId}
Get Payment Information
Returns the content of a payment object.
{
"enum": [
"domestic",
"sepa-credit-transfers",
"cross-border-credit-transfers",
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"domestic-credit-transfers-hr",
"hr-rtgs-payments",
"target-2-payments"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
Is contained if and only if the "Signature" element is contained in the header of the request.
A signature of the request by the TPP on application level. This might be mandated by ASPSP.
The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples
- Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)"
- iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0"
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Conflict
Unsuported Media Type
Too Many Requests
Internal Server Error
Service Unavailable
/bulk-payments/{payment-product}/{paymentId}
Get Payment Information
Returns the content of a payment object.
{
"enum": [
"domestic",
"sepa-credit-transfers",
"cross-border-credit-transfers",
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"domestic-credit-transfers-hr",
"hr-rtgs-payments",
"target-2-payments",
"pain001-credit-transfers-hr"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
Is contained if and only if the "Signature" element is contained in the header of the request.
A signature of the request by the TPP on application level. This might be mandated by ASPSP.
The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples
- Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)"
- iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0"
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}application/xml
Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Conflict
Unsuported Media Type
Too Many Requests
Internal Server Error
Service Unavailable
/{payment-service}/{payment-product}/{paymentId}
Payment Cancellation Request
This method initiates the cancellation of a payment. Depending on the payment-service, the payment-product and the ASPSP's implementation, this TPP call might be sufficient to cancel a payment. If an authorisation of the payment cancellation is mandated by the ASPSP, a corresponding hyperlink will be contained in the response message.
Cancels the addressed payment with resource identification paymentId if applicable to the payment-service, payment-product and received in product related timelines (e.g. before end of business day for scheduled payments of the last business day before the scheduled execution day).
The response to this DELETE command will tell the TPP whether the
- access method was rejected
- access method was successful, or
- access method is generally applicable, but further authorisation processes are needed.
{
"enum": [
"payments",
"periodic-payments",
"bulk-payments"
]
}{
"enum": [
"sepa-credit-transfers",
"cross-border-credit-transfers",
"domestic-credit-transfers-hr",
"domestic-credit-transfers-bgn",
"domestic-budget-transfers-bgn",
"pain001-credit-transfers-hr"
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
Is contained if and only if the "Signature" element is contained in the header of the request.
A signature of the request by the TPP on application level. This might be mandated by ASPSP.
The certificate used for signing the request, in base64 encoding. Must be contained if a signature is contained.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available. Examples
- Android: "Myappa/1.2 Dalvik/2.1.0 (Linux; U; Android 6.0.1; vivo 1610 Build/MMB29M)"
- iOS: "MyApp/1 iPhone5,2 iOS/10_1 CFNetwork/808.3 Darwin/16.3.0"
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
{
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
}UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}Received
{
"headers": {
"X-Request-ID": {
"type": "string",
"default": "99391c7e-ad88-49ec-a2ad-99ddcb1f7721"
}
},
"schema": {
"type": "object",
"example": {
"transactionStatus": "RCVD",
"_links": []
}
}
}No Content
Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Conflict
Unsuported Media Type
Too Many Requests
Internal Server Error
Service Unavailable
/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId}
/{payment-service}/{payment-product}/{paymentId}/authorisations
/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations
Definitions
Generic JSON response body consistion of the corresponding payment initation JSON body together with an optional transaction status field.
{
"type": "object",
"required": [
"debtorAccount",
"instructedAmount",
"creditorAccount",
"creditorName"
],
"properties": {
"transactionStatus": {
"$ref": "#/definitions/transactionStatus"
},
"endToEndIdentification": {
"type": "string",
"maxLength": 35
},
"instructedAmount": {
"$ref": "#/definitions/amount"
},
"debtorAccount": {
"$ref": "#/definitions/accountReference"
},
"creditorAccount": {
"$ref": "#/definitions/accountReference"
},
"creditorName": {
"$ref": "#/definitions/creditorName"
},
"creditorAddress": {
"$ref": "#/definitions/address"
},
"creditorAgent": {
"$ref": "#/definitions/bicfi"
},
"remittanceInformationUnstructured": {
"$ref": "#/definitions/remittanceInformationUnstructured"
},
"remittanceInformationStructured": {
"type": "string"
},
"creditorAgentName": {
"type": "string"
},
"chargeBearer": {
"$ref": "#/definitions/ChargeBearer"
},
"serviceLevel": {
"$ref": "#/definitions/ServiceLevel"
},
"requestedExecutionDate": {
"description": "{DATE}",
"example": "2015-05-05",
"type": "string",
"format": "date"
},
"purposeCode": {
"type": "string",
"example": "S00014"
},
"ultimateCreditor": {
"type": "string"
},
"ultimateDebtor": {
"type": "string"
}
}
}
Generic JSON response body consistion of the corresponding periodic payment initation JSON body together with an optional transaction status field.
{
"type": "object",
"required": [
"debtorAccount",
"instructedAmount",
"creditorAccount",
"creditorName",
"startDate",
"frequency"
],
"properties": {
"endToEndIdentification": {
"type": "string",
"maxLength": 35
},
"debtorAccount": {
"$ref": "#/definitions/accountReference"
},
"instructedAmount": {
"$ref": "#/definitions/amount"
},
"creditorAccount": {
"$ref": "#/definitions/accountReference"
},
"creditorAgent": {
"$ref": "#/definitions/bicfi"
},
"creditorName": {
"$ref": "#/definitions/creditorName"
},
"creditorAddress": {
"$ref": "#/definitions/address"
},
"remittanceInformationUnstructured": {
"$ref": "#/definitions/remittanceInformationUnstructured"
},
"remittanceInformationStructured": {
"type": "string"
},
"creditorAgentName": {
"type": "string"
},
"chargeBearer": {
"$ref": "#/definitions/ChargeBearer"
},
"serviceLevel": {
"$ref": "#/definitions/ServiceLevel"
},
"requestedExecutionDate": {
"description": "{DATE}",
"example": "2015-05-05",
"type": "string",
"format": "date"
},
"purposeCode": {
"type": "string",
"example": "S00014"
},
"ultimateCreditor": {
"type": "string"
},
"ultimateDebtor": {
"type": "string"
},
"startDate": {
"$ref": "#/definitions/startDate"
},
"endDate": {
"$ref": "#/definitions/endDate"
},
"executionRule": {
"$ref": "#/definitions/executionRule"
},
"frequency": {
"$ref": "#/definitions/frequencyCode"
},
"dayOfExecution": {
"$ref": "#/definitions/dayOfExecution"
},
"transactionStatus": {
"$ref": "#/definitions/transactionStatus"
}
}
}
Generic JSON response body consistion of the corresponding bulk payment initation JSON body together with an optional transaction status field.
{
"type": "object",
"required": [
"payments",
"debtorAccount"
],
"properties": {
"batchBookingPreferred": {
"$ref": "#/definitions/batchBookingPreferred"
},
"requestedExecutionDate": {
"type": "string",
"format": "date"
},
"debtorAccount": {
"$ref": "#/definitions/accountReference"
},
"payments": {
"description": "A list of generic JSON bodies payment initations for bulk payments via JSON.\n",
"type": "array",
"items": {
"$ref": "#/definitions/paymentInitiationBulkElement_json"
}
},
"transactionStatus": {
"$ref": "#/definitions/transactionStatus"
}
}
}
{
"type": "object",
"required": [
"instructedAmount",
"creditorAccount",
"creditorName"
],
"properties": {
"endToEndIdentification": {
"type": "string",
"maxLength": 35
},
"instructedAmount": {
"$ref": "#/definitions/amount"
},
"debtorAccount": {
"$ref": "#/definitions/accountReference"
},
"creditorAccount": {
"$ref": "#/definitions/accountReference"
},
"creditorName": {
"$ref": "#/definitions/creditorName"
},
"creditorAddress": {
"$ref": "#/definitions/address"
},
"creditorAgent": {
"$ref": "#/definitions/bicfi"
},
"remittanceInformationUnstructured": {
"$ref": "#/definitions/remittanceInformationUnstructured"
},
"remittanceInformationStructured": {
"type": "string"
},
"creditorAgentName": {
"type": "string"
},
"chargeBearer": {
"$ref": "#/definitions/ChargeBearer"
},
"serviceLevel": {
"$ref": "#/definitions/ServiceLevel"
},
"requestedExecutionDate": {
"description": "{DATE}",
"example": "2015-05-05",
"type": "string",
"format": "date"
},
"purposeCode": {
"type": "string",
"example": "S00014"
},
"ultimateCreditor": {
"type": "string"
},
"ultimateDebtor": {
"type": "string"
}
}
}
Reference to an account by either
- IBAN, of a payment accounts, or
- BBAN, for payment accounts if there is no IBAN, or
- the Primary Account Number (PAN) of a card, can be tokenised by the ASPSP due to PCI DSS requirements, or
- the Primary Account Number (PAN) of a card in a masked form, or
- an alias to access a payment account via a registered mobile phone number (MSISDN).
{
"type": "object",
"properties": {
"iban": {
"$ref": "#/definitions/iban"
},
"bban": {
"$ref": "#/definitions/bban"
},
"currency": {
"$ref": "#/definitions/currencyCode"
},
"debtorName": {
"type": "string"
}
}
}
Day of execution as string.
This string consists of up two characters. Leading zeroes are not allowed.
31 is ultimo of the month.
{
"type": "string",
"maxLength": 2,
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"28",
"29",
"30",
"31"
]
}
{
"title": "chargeBearer",
"example": "CRED",
"x-enum-elements": [
{
"name": "CRED",
"description": ""
},
{
"name": "DEBT",
"description": ""
},
{
"name": "SHAR",
"description": ""
},
{
"name": "SLEV",
"description": ""
}
],
"type": "string",
"enum": [
"CRED",
"DEBT",
"SHAR"
]
}
{
"title": "Service level according to ISO 20022",
"example": "SEPA",
"type": "string",
"enum": [
"SEPA",
"URGP",
"SDVA",
"NEXT",
"SPOT",
"NURG"
]
}
IBAN of an account.
{
"type": "string",
"pattern": "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}",
"example": "FR7612345987650123456789014"
}
Basic Bank Account Number (BBAN) Identifier.
This data element can be used in the body of the consent request. Message for retrieving account access consent from this account. This data elements is used for payment accounts which have no IBAN. ISO20022: Basic Bank Account Number (BBAN).
Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer.
{
"type": "string",
"pattern": "[a-zA-Z0-9]{1,30}",
"example": "BARC12345612345678"
}
{
"type": "object",
"required": [
"currency",
"amount"
],
"properties": {
"currency": {
"$ref": "#/definitions/currencyCode"
},
"amount": {
"$ref": "#/definitions/amountValue"
}
},
"example": {
"currency": "EUR",
"amount": "123"
}
}
{
"type": "string",
"pattern": "-?[0-9]{1,14}(\\.[0-9]{1,3})?",
"example": "5877.78"
}
BICFI
{
"type": "string",
"pattern": "[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}",
"example": "AAAADEBBXXX"
}
Creditor name.
{
"type": "string",
"maxLength": 70,
"example": "Creditor Name"
}
Creditor agent name.
{
"type": "string",
"maxLength": 70,
"example": "Creditor Agent Name"
}
If this element equals 'true', the PSU prefers only one booking entry. If this element equals 'false', the PSU prefers individual booking of all contained individual transactions.
The ASPSP will follow this preference according to contracts agreed on with the PSU.
{
"type": "boolean",
"example": false
}
{
"type": "object",
"required": [
"country"
],
"properties": {
"street": {
"type": "string",
"maxLength": 70
},
"buildingNumber": {
"type": "string"
},
"city": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"country": {
"$ref": "#/definitions/countryCode"
}
},
"example": {
"street": "rue blue",
"buildingnNumber": "89",
"city": "Paris",
"postalCode": "75000",
"country": "FR"
}
}
Unstructured remittance information.
{
"type": "string",
"maxLength": 140,
"example": "Ref Number Merchant"
}
The first applicable day of execution starting from this date is the first payment.
{
"type": "string",
"format": "date"
}
The last applicable day of execution. If not given, it is an infinite standing order.
{
"type": "string",
"format": "date"
}
ISO 3166 ALPHA2 country code.
{
"type": "string",
"pattern": "[A-Z]{2}",
"example": "SE"
}
"following" or "preceding" supported as values. 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.
{
"type": "string",
"enum": [
"following",
"preceding"
]
}
{
"type": "string",
"enum": [
"Daily",
"Weekly",
"EveryTwoWeeks",
"Monthly",
"EveryTwoMonths",
"Quarterly",
"SemiAnnual",
"Annual",
"MonthlyVariable"
]
}
Authentication Object
{
"title": "authenticationObject",
"type": "object",
"properties": {
"authenticationType": {
"$ref": "#/definitions/authenticationType"
},
"authenticationVersion": {
"description": "Depending on the \"authenticationType\".\nThis version can be used by differentiating authentication tools used within performing OTP generation in the same authentication type.\nThis version can be referred to in the ASPSP?s documentation.",
"type": "string"
},
"authenticationMethodId": {
"description": "An identification provided by the ASPSP for the later identification of the authentication method selection.",
"example": "myAuthenticationID",
"type": "string",
"maxLength": 35
},
"name": {
"description": "This is the name of the authentication method defined by the PSU in the Online Banking frontend of the ASPSP.\nAlternatively this could be a description provided by the ASPSP like \"SMS OTP on phone +49160 xxxxx 28\".\nThis name shall be used by the TPP when presenting a list of authentication methods to the PSU, if available.",
"example": "SMS OTP on phone +49160 xxxxx 28",
"type": "string"
},
"explanation": {
"description": "Detailed information about the SCA method for the PSU.",
"example": "Detailed information about the SCA method for the PSU.",
"type": "string"
}
},
"required": [
"authenticationType",
"authenticationMethodId"
]
}
Type of the authentication method.
More authentication types might be added during implementation projects and documented in the ASPSP documentation.
- 'SMS_OTP': An SCA method, where an OTP linked to the transaction to be authorised is sent to the PSU through a SMS channel.
- 'CHIP_OTP': An SCA method, where an OTP is generated by a chip card, e.g. an TOP derived from an EMV cryptogram. To contact the card, the PSU normally needs a (handheld) device. With this device, the PSU either reads the challenging data through a visual interface like flickering or the PSU types in the challenge through the device key pad. The device then derives an OTP from the challenge data and displays the OTP to the PSU.
- 'PHOTO_OTP': An SCA method, where the challenge is a QR code or similar encoded visual data which can be read in by a consumer device or specific mobile app. The device resp. the specific app than derives an OTP from the visual challenge data and displays the OTP to the PSU.
- 'PUSH_OTP': An OTP is pushed to a dedicated authentication APP and displayed to the PSU.
{
"title": "authenticationType",
"example": "SMS_OTP",
"type": "string",
"enum": [
"SMS_OTP",
"CHIP_OTP",
"PHOTO_OTP",
"PUSH_OTP"
]
}
It is contained in addition to the data element 'chosenScaMethod' if challenge data is needed for SCA. In rare cases this attribute is also used in the context of the 'startAuthorisationWithPsuAuthentication' link.
{
"title": "challengeData",
"type": "object",
"properties": {
"image": {
"description": "PNG data (max. 512 kilobyte) to be displayed to the PSU,\nBase64 encoding, cp. [RFC4648].\nThis attribute is used only, when PHOTO_OTP or CHIP_OTP\nis the selected SCA method.",
"type": "string"
},
"data": {
"description": "String challenge data",
"type": "string"
},
"imageLink": {
"description": "A link where the ASPSP will provides the challenge image for the TPP.",
"type": "string"
},
"otpMaxLength": {
"description": "The maximal length for the OTP to be typed in by the PSU.",
"type": "integer",
"format": "int32"
},
"otpFormat": {
"$ref": "#/definitions/OtpFormat"
},
"additionalInformation": {
"description": "Additional explanation for the PSU to explain\ne.g. fallback mechanism for the chosen SCA method.\nThe TPP is obliged to show this to the PSU.",
"type": "string"
}
}
}
Link to a resource
{
"type": "object",
"properties": {
"href": {
"$ref": "#/definitions/hrefEntry"
}
}
}
Link to a resource
{
"type": "string",
"example": "/v1/payments/sepa-credit-transfers/1234-wertiq-983"
}
ISO 4217 Alpha 3 currency code.
{
"type": "string",
"pattern": "[A-Z]{3}",
"example": "EUR"
}
Body of the JSON response with SCA Status
{
"title": "scaStatusResponse",
"type": "object",
"properties": {
"scaStatus": {
"$ref": "#/definitions/scaStatus"
}
}
}
This data element is containing information about the status of the SCA method applied.
The following codes are defined for this data type.
- 'received': An authorisation or cancellation-authorisation resource has been created successfully.
- 'psuIdentified': The PSU related to the authorisation or cancellation-authorisation resource has been identified.
- 'psuAuthenticated': The PSU related to the authorisation or cancellation-authorisation resource has been identified and authenticated e.g. by a password or by an access token.
- 'scaMethodSelected': The PSU/TPP has selected the related SCA routine. If the SCA method is chosen implicitly since only one SCA method is available, then this is the first status to be reported instead of 'received'.
- 'started': The addressed SCA routine has been started.
- 'finalised': The SCA routine has been finalised successfully.
- 'failed': The SCA routine failed
- 'exempted': SCA was exempted for the related transaction, the related authorisation is successful.
{
"title": "scaStatus",
"example": "received",
"type": "string",
"enum": [
"received",
"psuIdentified",
"psuAuthenticated",
"scaMethodSelected",
"started",
"finalised",
"failed",
"exempted"
]
}
The transaction status is filled with codes of the ISO 20022 data table:
- 'ACCC': 'AcceptedSettlementCompleted' - Settlement on the creditor's account has been completed.
- '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.
Usage: this can be used by the first agent to report to the debtor that the transaction has been completed.
Warning: this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.
- 'ACSP': 'AcceptedSettlementInProcess' - All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation 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 account.
- 'RCVD': 'Received' - Payment initiation has been received by the receiving agent.
- 'PDNG': 'Pending' - Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.
- 'RJCT': 'Rejected' - Payment initiation or individual transaction included in the payment initiation has been rejected.
- 'CANC': 'Cancelled' Payment initiation has been cancelled before execution Remark: This codeis accepted as new code by ISO20022.
- 'ACFC': 'AcceptedFundsChecked' - Preceding check of technical validation and customer profile was successful and an automatic funds check was positive . Remark: This code is accepted as new code by ISO20022.
- 'PATC': 'PartiallyAcceptedTechnical' Correct The payment initiation needs multiple authentications, where some but not yet all have been performed. Syntactical and semantical validations are successful. Remark: This code is accepted as new code by ISO20022.
- 'PART': 'PartiallyAccepted' - A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status. Remark: This code may be used only in case of bulk payments. It is only used in a situation where all mandated authorisations have been applied, but some payments have been rejected.
{
"type": "string",
"enum": [
"ACCC",
"ACCP",
"ACSC",
"ACSP",
"ACTC",
"ACWC",
"ACWP",
"RCVD",
"PDNG",
"RJCT",
"CANC",
"ACFC",
"PATC",
"PART"
],
"example": "ACCP"
}
Category of the TPP message category
{
"title": "tppMessageCategory",
"example": "ERROR",
"type": "string",
"enum": [
"ERROR",
"WARNING"
]
}
A _link object with all availabel link types
{
"title": "_linksAll",
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppIOS": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppAndroid": {
"$ref": "#/definitions/hrefType"
},
"scaOAuth": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisation": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithPsuIdentification": {
"$ref": "#/definitions/hrefType"
},
"updatePsuIdentification": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithProprietaryData": {
"$ref": "#/definitions/hrefType"
},
"updateProprietaryData": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithPsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"updatePsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithEncryptedPsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"updateEncryptedPsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithAuthenticationMethodSelection": {
"$ref": "#/definitions/hrefType"
},
"selectAuthenticationMethod": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithTransactionAuthorisation": {
"$ref": "#/definitions/hrefType"
},
"authoriseTransaction": {
"$ref": "#/definitions/hrefType"
},
"self": {
"$ref": "#/definitions/hrefType"
},
"status": {
"$ref": "#/definitions/hrefType"
},
"scaStatus": {
"$ref": "#/definitions/hrefType"
},
"account": {
"$ref": "#/definitions/hrefType"
},
"balances": {
"$ref": "#/definitions/hrefType"
},
"transactions": {
"$ref": "#/definitions/hrefType"
},
"transactionDetails": {
"$ref": "#/definitions/hrefType"
},
"cardAccount": {
"$ref": "#/definitions/hrefType"
},
"cardTransactions": {
"$ref": "#/definitions/hrefType"
},
"first": {
"$ref": "#/definitions/hrefType"
},
"next": {
"$ref": "#/definitions/hrefType"
},
"previous": {
"$ref": "#/definitions/hrefType"
},
"last": {
"$ref": "#/definitions/hrefType"
},
"download": {
"$ref": "#/definitions/hrefType"
}
}
}
A list of hyperlinks to be recognised by the TPP. The actual hyperlinks used in the response depend on the dynamical decisions of the ASPSP when processing the request.
Remark: All links can be relative or full links, to be decided by the ASPSP.
Type of links admitted in this response, (further links might be added for ASPSP defined extensions):
- 'scaRedirect': In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browser.
- 'scaApp2AppIOS': In case of an App2App Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU mobile device.
- 'scaApp2AppAndroid': In case of an App2App Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU mobile device.
- 'scaOAuth': In case of a SCA OAuth2 Approach, the ASPSP is transmitting the URI where the configuration of the Authorisation Server can be retrieved. The configuration follows the OAuth 2.0 Authorisation Server Metadata specification.
- 'updatePsuIdentification': The link to the authorisation or cancellation authorisation sub-resource, where PSU identification data needs to be uploaded.
- 'startAuthorisationWithPsuAuthentication': The link to the authorisation or cancellation authorisation sub-resource, where PSU authentication data needs to be uploaded.
- 'startAuthorisationWithEncryptedPsuAuthentication': Same as startAuthorisactionWithPsuAuthentication where the authentication data need to be encrypted on application layer in uploading.
- 'selectAuthenticationMethod': The link to the authorisation or cancellation authorisation sub-resource, where the selected authentication method needs to be uploaded. This link is contained under exactly the same conditions as the data element 'scaMethods'.
- 'authoriseTransaction': The link to the authorisation or cancellation authorisation sub-resource, where the authorisation data has to be uploaded, e.g. the TOP received by SMS.
- 'scaStatus': The link to retrieve the scaStatus of the corresponding authorisation sub-resource.
{
"title": "_linksStartScaProcess",
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppIOS": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppAndroid": {
"$ref": "#/definitions/hrefType"
},
"scaOAuth": {
"$ref": "#/definitions/hrefType"
},
"updatePsuIdentification": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithPsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"startAuthorisationWithEncryptedPsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"selectAuthenticationMethod": {
"$ref": "#/definitions/hrefType"
},
"authoriseTransaction": {
"$ref": "#/definitions/hrefType"
},
"scaStatus": {
"$ref": "#/definitions/hrefType"
}
}
}
The format type of the OTP to be typed in. The admitted values are "characters" or "integer".
{
"title": "OtpFormat",
"example": "characters",
"type": "string",
"enum": [
"characters",
"integer"
]
}
An array of all authorisationIds
{
"title": "authorisations",
"type": "object",
"properties": {
"authorisationIds": {
"description": "An array of all authorisationIds",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"authorisationIds"
]
}
Body of the JSON response for a Start SCA authorisation request.
{
"title": "startScaprocessResponse",
"type": "object",
"properties": {
"scaStatus": {
"$ref": "#/definitions/scaStatus"
},
"authorisationId": {
"description": "Resource identification of the related SCA",
"example": "123auth456",
"type": "string"
},
"scaMethods": {
"description": "This data element might be contained, if SCA is required and if the PSU has a choice between different\nauthentication methods.\n\nDepending on the risk management of the ASPSP this choice might be offered before or after the PSU\nhas been identified with the first relevant factor, or if an access token is transported.\n\nIf this data element is contained, then there is also an hyperlink of type 'startAuthorisationWithAuthenticationMethodSelection'\ncontained in the response body.\n\nThese methods shall be presented towards the PSU for selection by the TPP.",
"type": "array",
"items": {
"$ref": "#/definitions/authenticationObject"
}
},
"chosenScaMethod": {
"$ref": "#/definitions/authenticationObject"
},
"challengeData": {
"$ref": "#/definitions/challengeData"
},
"_links": {
"$ref": "#/definitions/_linksStartScaProcess"
},
"psuMessage": {
"description": "Text to be displayed to the PSU",
"type": "string",
"maxLength": 512
}
},
"required": [
"scaStatus",
"authorisationId",
"_links"
]
}
Body of the response for a successful payment initiation status request in case of an JSON based endpoint.
{
"type": "object",
"required": [
"transactionStatus"
],
"properties": {
"transactionStatus": {
"$ref": "#/definitions/transactionStatus"
},
"fundsAvailable": {
"type": "boolean"
}
}
}
{
"title": "tppMessage400_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"$ref": "#/definitions/MessageCode400_PIS"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
{
"title": "tppMessage401_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"$ref": "#/definitions/MessageCode401_PIS"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
{
"title": "tppMessage403_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"$ref": "#/definitions/MessageCode403_PIS"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
{
"title": "tppMessage404_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"$ref": "#/definitions/MessageCode404_PIS"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
{
"title": "tppMessage405_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"description": "Message codes defined for payment cancelations PIS for HTTP Error code 405 (METHOD NOT ALLOWED).",
"example": "SERVICE_INVALID",
"type": "string",
"default": "SERVICE_INVALID"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
{
"title": "tppMessage409_PIS",
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"description": "Message codes defined for PIS for HTTP Error code 409 (CONFLICT).",
"example": "STATUS_INVALID",
"type": "string",
"default": "STATUS_INVALID"
},
"path": {
"type": "string"
},
"text": {
"description": "Additional explaining text to the TPP.",
"type": "string",
"maxLength": 512
}
},
"required": [
"category",
"code"
]
}
Message codes defined for PIS for HTTP Error code 400 (BAD_REQUEST).
{
"title": "MessageCode400_PIS",
"example": "FORMAT_ERROR",
"type": "string",
"enum": [
"FORMAT_ERROR",
"PARAMETER_NOT_CONSISTENT",
"PARAMETER_NOT_SUPPORTED",
"SERVICE_INVALID",
"RESOURCE_UNKNOWN",
"RESOURCE_EXPIRED",
"RESOURCE_BLOCKED",
"TIMESTAMP_INVALID",
"PERIOD_INVALID",
"SCA_METHOD_UNKNOWN",
"CONSENT_UNKNOWN",
"PAYMENT_FAILED",
"EXECUTION_DATE_INVALID"
]
}
Message codes defined for PIS for HTTP Error code 401 (UNAUTHORIZED).
{
"title": "MessageCode401_PIS",
"example": "CERTIFICATE_INVALID",
"type": "string",
"enum": [
"CERTIFICATE_INVALID",
"CERTIFICATE_EXPIRED",
"CERTIFICATE_BLOCKED",
"CERTIFICATE_REVOKE",
"CERTIFICATE_MISSING",
"SIGNATURE_INVALID",
"SIGNATURE_MISSING",
"CORPORATE_ID_INVALID",
"PSU_CREDENTIALS_INVALID",
"CONSENT_INVALID",
"CONSENT_EXPIRED",
"TOKEN_UNKNOWN",
"TOKEN_INVALID",
"TOKEN_EXPIRED",
"REQUIRED_KID_MISSING"
]
}
Message codes defined defined for PIS for PIS for HTTP Error code 403 (FORBIDDEN).
{
"title": "MessageCode403_PIS",
"example": "CONSENT_UNKNOWN",
"type": "string",
"enum": [
"CONSENT_UNKNOWN",
"SERVICE_BLOCKED",
"RESOURCE_UNKNOWN",
"RESOURCE_EXPIRED",
"PRODUCT_INVALID"
]
}
Message codes defined for PIS for HTTP Error code 404 (NOT FOUND).
{
"title": "MessageCode404_PIS",
"example": "RESOURCE_UNKNOWN",
"type": "string",
"enum": [
"RESOURCE_UNKNOWN",
"PRODUCT_UNKNOWN"
]
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 400.
{
"title": "Error400_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage400_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 401.
{
"title": "Error401_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage401_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 403.
{
"title": "Error403_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage403_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 404.
{
"title": "Error404_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage404_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 405.
{
"title": "Error405_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage405_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}
NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 409.
{
"title": "Error409_NG_PIS",
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessage409_PIS"
}
},
"_links": {
"$ref": "#/definitions/_linksAll"
}
}
}