Paths
/{payment-service}/domestic-budget-transfers-bgn
Payment initiation request
'This method is used to initiate a payment at the ASPSP. Variants of Payment Initiation Requests This method to initiate a payment initiation at the ASPSP can be sent with a JSON body or with XML pain.001 format. There are the following payment products: Payment products with payment information in JSON format: domestic-credit-transfers-bgn domestic-budget-transfers-bgn sepa-credit-transfers cross-border-transfers Payment products with payment information in pain.001 XML format: pain.001-domestic-credit-transfers-bgn pain.001-domestic-budget-transfers-bgn pain.001-sepa-credit-transfers pain.001-cross-border-transfers.'
{
"enum": [
"payments"
]
}ID of the request, unique to the call, as determined by the initiating party. This is the unique ID of TPP for the payment initiation regarding PSD2 article 46b, 47 and EBA RTS article 29.
Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP’s documentation. Is not contained if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in a preceding AIS service in the same session. .
Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. In this case, the mean and use is then defined in the ASPSP’s documentation.
Identification of a Corporate in the Online Channels Might be mandated in the ASPSP’s documentation. Only used in a corporate context.
This is describing the type of the identification needed by the ASPSP to identify the PSU-Corporate-ID content. Mean and use is defined in the ASPSP’s documentation. Only used in a corporate context.
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
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}"
}Bearer Token. Is contained only, if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session.
If it equals "true", the TPP prefers a redirect over an embedded SCA approach. If it equals "false", the TPP prefers not to be redirected for SCA. The ASPSP will then choose between the Embedded or the Decoupled SCA approach, depending on the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the SCA method chosen by the TPP/PSU.
URI of the TPP, where the transaction flow shall be redirected to after a Redirect. Mandatory for the SCA OAuth Approach.
If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method. This might be ignored by the ASPSP.
If it equals "true", the TPP prefers to start the authorisation process separately, e.g. because of the usage of a signing basket. This preference might be ignored by the ASPSP, if a signing basket is not supported as functionality.
If it equals "false" or if the parameter is not used, there is no preference of the TPP. This especially indicates that the TPP assumes a direct authorisation of the transaction in the next step, without using a signing basket.
{
"enum": [
"true",
"false"
]
}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, see above.
Payment initiation instruction. The payment data to be transported in the request body are dependent of the chosen API endpoint.
OK_Created
Validation error occurred. This code will cover malformed syntax in request or incorrect data in payload.
The TPP or the PSU is not correctly authorized to perform the request. Retry the request with correct authentication information.
Returned if the resource that was referenced in the path exists but cannot be accessed by the TPP or the PSU. This code should only be used for non-sensitive id references as it will reveal that the resource exists even though it cannot be accessed.
Returned if the resource that was referenced in the path does not exist or cannot be referenced by the TPP or the PSU. When in doubt if a specific id in the path is sensitive or not, use http code 404 instead of 403.
This code is only sent when the http method (PUT, POST, DELETE, GET etc) is not supported on a specific endpoint. It has nothing to do with the consent, payment or account information data model.
Internal server error occurred.
/{payment-service}/domestic-credit-transfers-bgn
Payment initiation request
'This method is used to initiate a payment at the ASPSP. Variants of Payment Initiation Requests This method to initiate a payment initiation at the ASPSP can be sent with a JSON body or with XML pain.001 format. There are the following payment products: Payment products with payment information in JSON format: domestic-credit-transfers-bgn domestic-budget-transfers-bgn sepa-credit-transfers cross-border-transfers Payment products with payment information in pain.001 XML format: pain.001-domestic-credit-transfers-bgn pain.001-domestic-budget-transfers-bgn pain.001-sepa-credit-transfers pain.001-cross-border-transfers.'
{
"enum": [
"payments"
]
}ID of the request, unique to the call, as determined by the initiating party. This is the unique ID of TPP for the payment initiation regarding PSD2 article 46b, 47 and EBA RTS article 29.
Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP’s documentation. Is not contained if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in a preceding AIS service in the same session. .
Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility. In this case, the mean and use is then defined in the ASPSP’s documentation.
Identification of a Corporate in the Online Channels Might be mandated in the ASPSP’s documentation. Only used in a corporate context.
This is describing the type of the identification needed by the ASPSP to identify the PSU-Corporate-ID content. Mean and use is defined in the ASPSP’s documentation. Only used in a corporate context.
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
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}"
}Bearer Token. Is contained only, if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session.
If it equals "true", the TPP prefers a redirect over an embedded SCA approach. If it equals "false", the TPP prefers not to be redirected for SCA. The ASPSP will then choose between the Embedded or the Decoupled SCA approach, depending on the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the SCA method chosen by the TPP/PSU.
URI of the TPP, where the transaction flow shall be redirected to after a Redirect. Mandatory for the SCA OAuth Approach.
If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method. This might be ignored by the ASPSP.
If it equals "true", the TPP prefers to start the authorisation process separately, e.g. because of the usage of a signing basket. This preference might be ignored by the ASPSP, if a signing basket is not supported as functionality.
If it equals "false" or if the parameter is not used, there is no preference of the TPP. This especially indicates that the TPP assumes a direct authorisation of the transaction in the next step, without using a signing basket.
{
"enum": [
"true",
"false"
]
}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, see above.
Payment initiation instruction. The payment data to be transported in the request body are dependent of the chosen API endpoint.
OK_Created
Validation error occurred. This code will cover malformed syntax in request or incorrect data in payload.
The TPP or the PSU is not correctly authorized to perform the request. Retry the request with correct authentication information.
Returned if the resource that was referenced in the path exists but cannot be accessed by the TPP or the PSU. This code should only be used for non-sensitive id references as it will reveal that the resource exists even though it cannot be accessed.
Returned if the resource that was referenced in the path does not exist or cannot be referenced by the TPP or the PSU. When in doubt if a specific id in the path is sensitive or not, use http code 404 instead of 403.
This code is only sent when the http method (PUT, POST, DELETE, GET etc) is not supported on a specific endpoint. It has nothing to do with the consent, payment or account information data model.
Internal server error occurred.
Definitions
Payment initiation request for budget transfer in BGN in JSON format
{
"type": "object",
"properties": {
"endToEndIdentification": {
"$ref": "#/definitions/endToEndIdentification"
},
"debtorAccount": {
"$ref": "#/definitions/account"
},
"ultimateDebtor": {
"$ref": "#/definitions/ultimateDebtor"
},
"instructedAmount": {
"$ref": "#/definitions/amountReference"
},
"creditorAccount": {
"$ref": "#/definitions/account"
},
"creditorAgent": {
"$ref": "#/definitions/creditorAgent"
},
"creditorName": {
"$ref": "#/definitions/creditorName"
},
"creditorAddress": {
"$ref": "#/definitions/address"
},
"purposeCode": {
"$ref": "#/definitions/purposeCode"
},
"remittanceInformationUnstructured": {
"$ref": "#/definitions/remittanceInformationUnstructured"
},
"serviceLevel": {
"$ref": "#/definitions/serviceLevel"
},
"budgetPaymentDetails": {
"$ref": "#/definitions/budgetPaymentDetails"
},
"obligedPersonName": {
"$ref": "#/definitions/obligedPersonName"
},
"requestedExecutionDate": {
"$ref": "#/definitions/requestedExecutionDate"
}
},
"additionalProperties": false,
"required": [
"debtorAccount",
"ultimateDebtor",
"instructedAmount",
"creditorAccount",
"creditorName",
"purposeCode",
"remittanceInformationUnstructured",
"budgetPaymentDetails",
"obligedPersonName"
],
"example": {
"instructedAmount": {
"currency": "BGN",
"amount": "123.50"
},
"purposeCode": "GOVT",
"debtorAccount": {
"iban": "BG94BANK12341234567890"
},
"creditorName": "Receiver TD NRA SOFIA",
"creditorAccount": {
"iban": "BG47BNBG96668123456789"
},
"budgetPaymentDetails": {
"regulatoryReportType": "1",
"taxPayerId": "9904281234",
"taxPayerType": "EGN",
"paymentCategory": "110000",
"fromDate": "2019-01-01",
"endDate": "2019-12-31"
},
"obligedPersonName": "Maria Nikolova Popova",
"ultimateDebtor": "Ivan Ivanov",
"remittanceInformationUnstructured": "Information for Merchant and payment"
}
}
Payment initiation request for credit transfer in BGN in JSON format
{
"type": "object",
"properties": {
"endToEndIdentification": {
"$ref": "#/definitions/endToEndIdentification"
},
"debtorAccount": {
"$ref": "#/definitions/account"
},
"instructedAmount": {
"$ref": "#/definitions/amountReference"
},
"creditorAccount": {
"$ref": "#/definitions/account"
},
"creditorAgent": {
"$ref": "#/definitions/creditorAgent"
},
"creditorName": {
"$ref": "#/definitions/creditorName"
},
"creditorAddress": {
"$ref": "#/definitions/address"
},
"remittanceInformationUnstructured": {
"$ref": "#/definitions/remittanceInformationUnstructured"
},
"serviceLevel": {
"$ref": "#/definitions/serviceLevel"
},
"requestedExecutionDate": {
"$ref": "#/definitions/requestedExecutionDate"
}
},
"additionalProperties": false,
"required": [
"debtorAccount",
"instructedAmount",
"creditorAccount",
"creditorName",
"remittanceInformationUnstructured"
],
"example": {
"instructedAmount": {
"currency": "BGN",
"amount": "123.50"
},
"debtorAccount": {
"iban": "BG94BANK12341234567890"
},
"serviceLevel": "URGP",
"creditorName": "Receiver Merchant123",
"creditorAccount": {
"iban": "BG96BGBK43210123456789"
},
"remittanceInformationUnstructured": "Information for Merchant and payment"
}
}
Amount Reference
{
"type": "object",
"properties": {
"currency": {
"$ref": "#/definitions/currency"
},
"amount": {
"$ref": "#/definitions/amount"
}
},
"additionalProperties": false,
"required": [
"currency",
"amount"
]
}
Account Reference
{
"type": "object",
"properties": {
"iban": {
"$ref": "#/definitions/iban"
},
"bban": {
"$ref": "#/definitions/bban"
},
"pan": {
"$ref": "#/definitions/pan"
},
"maskedPan": {
"$ref": "#/definitions/maskedPan"
},
"msisdn": {
"$ref": "#/definitions/msisdn"
},
"currency": {
"$ref": "#/definitions/currency"
}
},
"example": {
"iban": "BG94BANK12341234567890",
"currency": "EUR"
},
"additionalProperties": false
}
Name of obliged person, when the payer is different than obliged person
{
"type": "string",
"maxLength": 70,
"example": "Maria Nikolova Popova"
}
Mobile phone number.
{
"type": "string",
"maxLength": 35,
"example": "+898 898 888888"
}
Masked Primary Account Number
{
"type": "string",
"maxLength": 35,
"example": "123456xxxxxx1234"
}
Primary Account Number according to ISO/IEC 7812.
{
"type": "string",
"maxLength": 35,
"example": "5409050000000000"
}
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. Thisdata elements is used for payment Accounts which have no IBAN.
{
"type": "string",
"pattern": "[a-zA-Z0-9]{1,30}",
"example": "BARC12345612345678"
}
IBAN of an account
{
"type": "string",
"pattern": "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}",
"example": "BG94BANK12341234567890"
}
ISO 4217 Alpha 3 currency code
{
"type": "string",
"pattern": "[A-Z]{3}",
"example": "BGN"
}
The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. Negative amounts are signed by minus. The decimal separator is a dot.
{
"type": "string",
"example": "5877.78"
}
Address Reference
{
"type": "object",
"properties": {
"street": {
"type": "string",
"maxLength": 70,
"example": "London Street"
},
"buildingNumber": {
"type": "string",
"example": "25"
},
"city": {
"type": "string",
"example": "Sofia"
},
"postalCode": {
"type": "string",
"example": "1000"
},
"country": {
"$ref": "#/definitions/country-code"
}
},
"additionalProperties": false,
"required": [
"country"
]
}
ISO 3166 ALPHA2 country code
{
"type": "string",
"pattern": "[A-Z]{2}",
"example": "BG"
}
The unique transaction identification given by the payer
{
"type": "string",
"maxLength": 35,
"example": "4879"
}
Ultimate Debtor
{
"type": "string",
"maxLength": 70,
"example": "Ultimate Debtor"
}
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"
}
Purpose code is used for defining the purpose of the payment.
{
"type": "string",
"minLength": 4,
"maxLength": 4,
"enum": [
"GOVT"
]
}
A reference issued by the seller used to establish a link between the payment of an invoice and the invoice instance.
{
"type": "string",
"maxLength": 140,
"example": "Ref Number Merchant"
}
ISODate
{
"type": "string",
"format": "date"
}
Service Level Code
{
"type": "string",
"minLength": 4,
"maxLength": 4,
"enum": [
"SEPA",
"URGP",
"SDVA",
"NEXT",
"SPOT"
],
"example": "SEPA"
}
Details specific for the BGN budget payment.
{
"type": "object",
"properties": {
"regulatoryReportType": {
"$ref": "#/definitions/regulatoryReportType"
},
"documentNumber": {
"$ref": "#/definitions/documentNumber"
},
"documentDate": {
"$ref": "#/definitions/documentDate"
},
"taxPayerId": {
"$ref": "#/definitions/taxPayerId"
},
"taxPayerType": {
"$ref": "#/definitions/taxPayerType"
},
"paymentCategory": {
"$ref": "#/definitions/paymentCategory"
},
"fromDate": {
"$ref": "#/definitions/fromDate"
},
"endDate": {
"$ref": "#/definitions/endDate"
}
},
"additionalProperties": false,
"required": [
"regulatoryReportType"
]
}
1 - Declaration, 2 - Inspection Act, 3 - Penalty Decree, 4 - advance payment, 5 - batch property number ,6 - enforced collection order, 9 - others
{
"type": "string",
"minLength": 1,
"maxLength": 1,
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"9"
],
"example": "1"
}
Number of the document
{
"type": "string",
"example": "895412168"
}
Date of the document
{
"type": "string",
"format": "date",
"example": "2017-01-01"
}
Tax Identification
{
"type": "string",
"minLength": 9,
"maxLength": 10,
"pattern": "^[0-9]{9,10}?$",
"example": "9904281234"
}
Type of the tax
{
"type": "string",
"minLength": 3,
"maxLength": 3,
"enum": [
"EGN",
"EIK",
"PNF"
],
"example": "EGN"
}
Category of the payment
{
"type": "string",
"minLength": 6,
"maxLength": 6,
"pattern": "^[0-9]{6}?$",
"example": "110000"
}
Date from
{
"type": "string",
"format": "date",
"example": "2019-01-01"
}
Date End
{
"type": "string",
"format": "date",
"example": "2019-12-31"
}
Identification – Payment Transaction Status Code. Possible values - ACCP, ACSC, ACSP, ACTC, ACWC, ACWP, RCVD, PDNG, RJCT
{
"type": "string",
"enum": [
"ACCP",
"ACSC",
"ACSP",
"ACTC",
"ACWC",
"ACWP",
"RCVD",
"PDNG",
"RJCT"
],
"example": "ACCP"
}
Payment Initiation response in JSON format
{
"type": "object",
"properties": {
"transactionStatus": {
"$ref": "#/definitions/transactionStatus"
},
"paymentId": {
"$ref": "#/definitions/paymentId"
},
"transactionFees": {
"$ref": "#/definitions/transactionFees"
},
"transactionFeeIndicator": {
"$ref": "#/definitions/transactionFeeIndicator"
},
"scaMethods": {
"$ref": "#/definitions/scaMethods"
},
"chosenScaMethod": {
"$ref": "#/definitions/authenticationObject"
},
"challengeData": {
"$ref": "#/definitions/challengeData"
},
"_links": {
"$ref": "#/definitions/_links"
},
"psuMessage": {
"$ref": "#/definitions/psuMessage"
},
"tppMessages": {
"type": "array",
"items": {
"$ref": "#/definitions/tppMessages"
},
"description": "Messages to the TPP on operational issues."
}
},
"additionalProperties": false,
"required": [
"transactionStatus",
"paymentId",
"_links"
],
"example": {
"transactionStatus": "RCVD",
"paymentId": "1234-rtgsct-983",
"_links": {
"scaRedirect": {
"href": "https://www.testbank.com/asdfasdfasdf"
},
"self": {
"href": "/v1/payments/domestic-credit-transfers-bgn/1234-rtgsct-983"
}
}
}
}
Resource identification of the generated payment initiation resource.
{
"type": "string",
"example": "1234-rtgsct-983"
}
{
"$ref": "#/definitions/amountReference"
}
Transaction Fee Indicator.
{
"type": "boolean",
"example": true
}
This data element might be contained, if SCA is required and if the PSU has a choice between different
authentication methods.
Depending on the risk management of the ASPSP this choice might be offered before or after the PSU
has been identified with the first relevant factor, or if an access token is transported.
If this data element is contained, then there is also an hyperlink of type 'startAuthorisationWithAuthenticationMethodSelection'
contained in the response body.
These methods shall be presented towards the PSU for selection by the TPP.
{
"type": "array",
"items": {
"$ref": "#/definitions/authenticationObject"
}
}
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.
{
"type": "object",
"properties": {
"image": {
"type": "string",
"format": "byte",
"description": "PNG data (max. 512 kilobyte) to be displayed to the PSU, Base64 encoding, cp. [RFC 4648]. This attribute is used only, when PHOTO_OTP or CHIP_OTP is the selected SCA method."
},
"data": {
"type": "string",
"description": "String challenge data"
},
"imageLink": {
"type": "string",
"format": "url",
"description": "A link where the ASPSP will provides the challenge image for the TPP."
},
"otpMaxLength": {
"type": "integer",
"description": "The maximal length for the OTP to be typed in by the PSU."
},
"otpFormat": {
"type": "string",
"description": "The format type of the OTP to be typed in. The admitted values are “characters” or “integer”.",
"enum": [
"characters",
"integer"
]
},
"additionalInformation": {
"type": "string",
"description": "Additional explanation for the PSU to explain e.g. fallback mechanism for the chosen SCA method. The TPP is obliged to show this to the PSU."
}
},
"additionalProperties": false
}
Hyperlinks
{
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppIOS": {
"$ref": "#/definitions/hrefType"
},
"scaApp2AppAndroid": {
"$ref": "#/definitions/hrefType"
},
"scaOAuth": {
"$ref": "#/definitions/hrefType"
},
"updatePsuIdentification": {
"$ref": "#/definitions/hrefType"
},
"updateProprietaryData": {
"$ref": "#/definitions/hrefType"
},
"updatePsuAuthentication": {
"$ref": "#/definitions/hrefType"
},
"selectAuthenticationMethod": {
"$ref": "#/definitions/hrefType"
},
"authoriseTransaction": {
"$ref": "#/definitions/hrefType"
},
"self": {
"$ref": "#/definitions/hrefType"
},
"status": {
"$ref": "#/definitions/hrefType"
},
"account": {
"$ref": "#/definitions/hrefType"
},
"balances": {
"$ref": "#/definitions/hrefType"
},
"transactions": {
"$ref": "#/definitions/hrefType"
},
"transactionDetails": {
"$ref": "#/definitions/hrefType"
},
"first": {
"$ref": "#/definitions/hrefType"
},
"next": {
"$ref": "#/definitions/hrefType"
},
"previous": {
"$ref": "#/definitions/hrefType"
},
"last": {
"$ref": "#/definitions/hrefType"
},
"download": {
"$ref": "#/definitions/hrefType"
}
},
"additionalProperties": false
}
Text to be displayed to the PSU
{
"type": "string",
"maxLength": 512,
"example": "Text to be displayed to the PSU"
}
Authentication Object
{
"type": "object",
"properties": {
"authenticationType": {
"$ref": "#/definitions/authenticationType"
},
"authenticationVersion": {
"type": "string",
"description": "Depending on the \"authenticationType\". This version can be used by differentiating authentication tools used within performing OTP generation in the same authentication type. This version can be referred to in the ASPSP?s documentation."
},
"authenticationMethodId": {
"$ref": "#/definitions/authenticationMethodId"
},
"name": {
"type": "string",
"description": "This is the name of the authentication method defined by the PSU in the Online Banking frontend of the ASPSP. Alternatively this could be a description provided by the ASPSP like \"SMS OTP on phone +49160 xxxxx 28\". This 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"
},
"explanation": {
"type": "string",
"description": "Detailed information about the SCA method for the PSU.",
"example": "Detailed information about the SCA method for the PSU."
}
},
"additionalProperties": false,
"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.
{
"type": "string",
"enum": [
"SMS_OTP",
"CHIP_OTP",
"PHOTO_OTP",
"PUSH_OTP"
],
"example": "SMS_OTP"
}
An identification provided by the ASPSP for the later identification of the authentication method selection.
{
"type": "string",
"maxLength": 35,
"example": "myAuthenticationID"
}
Link to a resource
{
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Link to a resource",
"example": "/v1/payments/sepa-credit-transfers/1234-wertiq-983"
}
},
"additionalProperties": false,
"required": [
"href"
]
}
TPP Messages reference.
{
"properties": {
"category": {
"type": "string",
"enum": [
"ERROR",
"WARNING"
],
"description": "Only ”ERROR” or \"WARNING\" permitted"
},
"code": {
"type": "string"
},
"path": {
"type": "string"
},
"text": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"code",
"category"
]
}
Bad Request
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"FORMAT_ERROR",
"PARAMETER_NOT_SUPPORTED",
"SERVICE_INVALID",
"RESOURCE_UNKNOWN",
"RESOURCE_EXPIRED",
"TIMESTAMP_INVALID",
"PERIOD_INVALID",
"SCA_METHOD_UNKNOWN",
"CONSENT_UNKNOWN",
"PAYMENT_FAILED",
"EXECUTION_DATE_INVALID"
],
"example": "FORMAT_ERROR"
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Unauthorized
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"CERTIFICATE_INVALID",
"CERTIFICATE_EXPIRED",
"CERTIFICATE_BLOCKED",
"CERTIFICATE_REVOKED",
"CERTIFICATE_MISSING",
"SIGNATURE_INVALID",
"SIGNATURE_MISSING",
"PSU_CREDENTIALS_INVALID",
"CORPORATE_ID_INVALID",
"CONSENT_INVALID",
"CONSENT_EXPIRED",
"TOKEN_UNKNOWN",
"TOKEN_INVALID",
"TOKEN_EXPIRED",
"REQUIRED_KID_MISSING"
],
"example": "TOKEN_EXPIRED"
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Forbidden
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"SERVICE_BLOCKED",
"CONSENT_UNKNOWN",
"RESOURCE_UNKNOWN",
"RESOURCE_EXPIRED",
"PRODUCT_INVALID"
],
"example": "CONSENT_UNKNOWN"
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Not found
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"RESOURCE_UNKNOWN",
"PRODUCT_UNKNOWN"
]
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Method Not Allowed
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"SERVICE_INVALID"
]
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Internal Server Error
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/tppMessageCategory"
},
"code": {
"type": "string",
"enum": [
"INTERNAL_ERROR"
]
},
"path": {
"type": "string"
},
"text": {
"$ref": "#/definitions/tppMessageText"
}
},
"additionalProperties": false,
"required": [
"category",
"code"
]
}
}
},
"additionalProperties": false,
"required": [
"tppMessages"
]
}
Additional explaining text to the TPP.
{
"type": "string",
"maxLength": 512,
"example": "additional text information of the ASPSP up to 512 characters"
}
Category of the TPP message category
{
"type": "string",
"enum": [
"ERROR",
"WARNING"
],
"example": "ERROR"
}