Summary
The NextGenPSD2 Framework Version 1.2 offers a modern, open, harmonised and interoperable set of Application Programming Interfaces (APIs) as the safest and most efficient way to provide data securely. The NextGenPSD2 Framework reduces XS2A complexity and costs, addresses the problem of multiple competing standards in Europe and, aligned with the goals of the Euro Retail Payments Board, enables European banking customers to benefit from innovative products and services ('Banking as a Service') by granting TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data.
Futhermore this API definition contains only a subset of the methods, the ones which are mandatory or which are applicable in the BT ecosystem.
Some General Remarks Related to this version of the OpenAPI Specification:
- This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not an replacement in any sense. The main specification is (at the moment) allways the Implementation Guidelines of the Berlin Group PSD2 API.
- This API definition contains the REST-API for requests from the PISP to the ASPSP.
- This API definition contains the messages for all different approaches defined in the Implementation Guidelines. *
Changelog:
Version 1.0.4
- Dynamic generation of paymentId
- tppMessages error parameter is array instead of object
- GET Payment Details and GET Payment status paths now include the payment-product parameter (support values: ron-payment, other-currency-payment)
- various minor corrections and additions
Paths
/v2/{payment-service}/{payment-product}
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 for the payment product in the path.
There are the following payment products:
- Payment products with payment information in JSON format:
- ron-payment
- other-currency-payment
Furthermore the request body depends on the payment-service
- payments: A single payment initiation request.
In case of a JSON there are several JSON payment blocks contained in a joining list.
- periodic-payments: Create a standing order initiation resource for recurrent i.e. periodic payments addressable under {paymentId} with all data relevant for the corresponding payment product and the execution of the standing order contained in a JSON body.
This is the first step in the API to initiate the related recurring/periodic payment.
- bulk-payments: Create a bulk payment initiation resource addressable under {paymentId} with all data relevant for the corresponding payment product. This is the first step in the API to initiate the related bulk payment.
Single and mulitilevel SCA Processes
The Payment Initiation Requests are independent from the need of one ore multilevel SCA processing, i.e. independent from the number of authorisations needed for the execution of payments.
But the response messages are specific to either one SCA processing or multilevel SCA processing.
For payment initiation with multilevel SCA, this specification requires an explicit start of the authorisation, i.e. links directly associated with SCA processing like 'scaRedirect' or 'scaOAuth' cannot be contained in the response message of a Payment Initation Request for a payment, where multiple authorisations are needed. Also if any data is needed for the next action, like selecting an SCA method is not supported in the response, since all starts of the multiple authorisations are fully equal. In these cases, first an authorisation sub-resource has to be generated following the 'startAuthorisation' link.
Payment service:Possible values are: payments periodic-payments bulk-payments
{
"enum": [
"payments",
"periodic-payments",
"bulk-payments"
],
"x-enum-elements": [
{
"name": "payments",
"description": ""
},
{
"name": "periodic-payments",
"description": ""
},
{
"name": "bulk-payments",
"description": ""
}
]
}The following payment products are supported: - ron-payment - other-currency-payment
{
"enum": [
"ron-payment",
"other-currency-payment"
],
"x-enum-elements": [
{
"name": "ron-payment",
"description": ""
},
{
"name": "other-currency-payment",
"description": ""
}
]
}ID of the request, unique to the call, as determined by the initiating party.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
json body of BTPaymentInitiationRon or BTPaymentInitiationVal types
{
"schema": {
"type": "object",
"example": {
"debtorAccount": {
"iban": "RO98BTRLRONCRT0ABCDEFGHI"
},
"instructedAmount": {
"currency": "RON",
"amount": "50"
},
"creditorAccount": {
"iban": "RO98BTRLEURCRT0ABCDEFGHI"
},
"creditorName": "Dan Popescu",
"debtorId": "RO12345",
"endToEndIdentification": "Test",
"remittanceInformationUnstructured": "explicatii"
}
}
}application/json
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
CREATED
{
"schema": {
"type": "object",
"example": {
"paymentId": "273c540e6c534b1f8d873baf23728969ron",
"transactionStatus": "Submit",
"psuMessage": "Text to be displayed to the PSU",
"tppMessages": "Messages to the TPP on operational issues.",
"_links": {
"scaOAuth": {
"href": "https:\/\/api.apistorebt.ro\/bt\/sb\/oauth\/.well-known\/oauth-authorization-server"
},
"self": {
"href": "https:\/\/api.apistorebt.ro\/bt\/sb\/bt-psd2\/v3\/payments\/273c540e6c534b1f8d873baf23728969ron"
},
"status": {
"href": "https:\/\/api.apistorebt.ro\/bt\/sb\/bt-psd2\/v3\/payments\/273c540e6c534b1f8d873baf23728969ron\/status"
}
}
}
}
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Unsupported Media Type
Too Many Requests
Service Unavailable
Internal Server Error
/v2/{payment-service}/{payment-product}/{paymentId}
Get Payment Information
Returns the content of a payment object
Payment service:
Possible values are:
- payments
- periodic-payments
- bulk-payments
{
"enum": [
"payments",
"periodic-payments",
"bulk-payments"
],
"x-enum-elements": [
{
"name": "payments",
"description": ""
},
{
"name": "periodic-payments",
"description": ""
},
{
"name": "bulk-payments",
"description": ""
}
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "(GEO:)[0-9]{1,3}\\.[-][0-9]{6}\\,[-][0-9]{1,3}\\.[0-9]{6}"
}The following payment products are supported: - ron-payment - other-currency-payment
This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 Token endpoint.
OK
{
"schema": {
"type": "object",
"example": {
"debtorAccount": {
"iban": "RO98BTRLRONCRT0ABCDEFGHI"
},
"instructedAmount": {
"currency": "RON",
"amount": "50"
},
"creditorAccount": {
"iban": "RO98BTRLEURCRT0ABCDEFGHI"
},
"creditorName": "Dan Popescu",
"debtorId": "RO12345",
"endToEndIdentification": "Test",
"remittanceInformationUnstructured": "explicatii"
}
}
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Unsupported Media Type
Too Many Requests
Service Unavailable
Internal Server Error
/v2/{payment-service}/{payment-product}/{paymentId}/status
Payment initiation status request
Check the transaction status of a payment initiation.
Payment service:
Possible values are:
- payments
- periodic-payments
- bulk-payments
{
"enum": [
"payments",
"periodic-payments",
"bulk-payments"
],
"x-enum-elements": [
{
"name": "payments",
"description": ""
},
{
"name": "periodic-payments",
"description": ""
},
{
"name": "bulk-payments",
"description": ""
}
]
}Resource identification of the generated payment initiation resource.
ID of the request, unique to the call, as determined by the initiating party.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "(GEO:)[0-9]{1,3}\\.[-][0-9]{6}\\,[-][0-9]{1,3}\\.[0-9]{6}"
}The following payment products are supported: - ron-payment - other-currency-payment
This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 Token endpoint.
OK
{
"schema": {
"type": "object",
"example": {
"transactionStatus": "submit"
}
}
}Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Unsupported Media Type
Too Many Requests
Service Unavailable
Internal Server Error
/v2/{payment-service}/{payment-product}/confirmation
Bulk Payment confirmation request
This method is used to confirm a bulk payment at the ASPSP and change the bulk payment status from Initiated to Confirmed
Payment service:
Possible values are:
- bulk-payments
The following payment products are supported: - ron-payment
ID of the request, unique to the call, as determined by the initiating party.
The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP.
json body of BTBulkPaymentConfirmation type
{
"schema": {
"type": "object"
}
}application/json
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
This header should be in the form "Bearer Token", where Token is returned from the call to OAuth2 Token endpoint.
CREATED
Bad Request
Unauthorized
Forbidden
Not found
Method Not Allowed
Not Acceptable
Request Timeout
Unsupported Media Type
Too Many Requests
Service Unavailable
Definitions
{
"title": "BTPaymentInitiationResponse",
"type": "object",
"properties": {
"TransactionId": {
"description": "The ID of the initiated transaction",
"type": "string"
},
"TransactionStatus": {
"description": "Current status of the transaction",
"type": "string"
}
},
"required": [
"TransactionId"
]
}
{
"type": "object",
"properties": {
"debtorAccount": {
"properties": [],
"description": "Debtor Account",
"$ref": "#/definitions/Account"
},
"instructedAmount": {
"properties": {
"currency": {
"type": "string"
},
"amount": {
"type": "string"
}
},
"$ref": "#/definitions/Amount",
"description": "Amount Object"
},
"creditorAccount": {
"properties": {
"iban": {
"type": "string"
}
},
"$ref": "#/definitions/Account",
"description": "Creditor Account"
},
"creditorAgent": {
"type": "string",
"description": "BIC/SWIFT"
},
"creditorAgentName": {
"type": "string",
"description": "Creditor Bank Name"
},
"creditorName": {
"type": "string",
"description": "Creditor Name"
},
"creditorAddress": {
"properties": {
"street": {
"type": "string"
},
"buildingNumber": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
}
},
"description": "Credit Address",
"$ref": "#/definitions/Address"
},
"endToEndIdentification": {
"type": "string",
"description": "Transaction Reference"
},
"remittanceInformationUnstructured": {
"type": "string",
"description": "Merchant payment reference"
}
},
"example": "{\"instructedAmount\":{\"currency\":\"EUR\",\"amount\":\"100\"},\"debtorAccount\":{\"iban\":\"RO98BTRLEURCRT0ABCDEFGHI\"},\"creditorAccount\":{\"iban\":\"RO98BTRLEURCRT0ABCDEFGHJ\"},\"creditorAgent\":\"BTRLRO99\",\"creditorAgentName\":\"Banca Transilvania\",\"creditorName\":\"Creditor Name\",\"creditorAddress\":{\"street\":\"Street name\",\"buildingNumber\":\"Building number\",\"city\":\"City\",\"country\":\"RO\"},\"endToEndIdentification\":\"123456\",\"remittanceInformationUnstructured\":\"123456\"}",
"required": [
"instructedAmount",
"creditorAccount",
"creditorAgent",
"creditorAgentName",
"creditorName",
"creditorAddress"
],
"additionalProperties": false
}
{
"type": "object",
"properties": {
"debtorAccount": {
"properties": [],
"description": "Debtor Account",
"$ref": "#/definitions/Account"
},
"instructedAmount": {
"properties": {
"currency": {
"type": "string"
},
"amount": {
"type": "string"
}
},
"$ref": "#/definitions/Amount",
"description": "Amount Object"
},
"creditorAccount": {
"properties": {
"iban": {
"type": "string"
}
},
"$ref": "#/definitions/Account",
"description": "Creditor Account"
},
"creditorName": {
"type": "string",
"description": "Creditor Name"
},
"debtorId": {
"type": "string",
"description": "Debtor Fiscal Identification Number. Mandatory only for Treasury Payments."
},
"endToEndIdentification": {
"type": "string",
"description": "Transaction Reference"
},
"remittanceInformationUnstructured": {
"type": "string",
"description": "Merchant payment reference"
}
},
"example": "{ \"debtorAccount\": { \"iban\": \"RO98BTRLRONCRT0ABCDEFGHI\" }, \"instructedAmount\": { \"currency\": \"RON\", \"amount\": 50 }, \"creditorAccount\": { \"iban\": \"RO98BTRLEURCRT0ABCDEFGHI\" }, \"creditorName\": \"Dan Popescu\", \"debtorId\": \"RO12345\", \"endToEndIdentification\": \"Test\", \"remittanceInformationUnstructured\": \"explicatii\" }",
"required": [
"instructedAmount",
"creditorAccount",
"creditorName"
],
"additionalProperties": false
}
{
"properties": {
"debtorAccount": {
"description": "Debtor Account",
"$ref": "#/definitions/Account"
},
"payments": {
"description": "The array that contain the payments",
"$ref": "#/definitions/BulkPaymentsList"
}
},
"additionalProperties": false,
"required": [
"payments"
]
}
{
"properties": {
"paymentBulkId": {
"type": "string",
"description": "Bulk Payment Initiation resource identification"
}
},
"additionalProperties": false,
"required": [
"paymentBulkId"
]
}
{
"type": "array",
"items": {
"$ref": "#/definitions/BTPaymentInitiationRon"
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/BTPaymentInitiationVal"
}
}
{
"type": "array",
"items": {
"$ref": "#/definitions/BulkPayments"
}
}
{
"type": "object",
"properties": {
"instructedAmount": {
"description": "Amount Object",
"$ref": "#/definitions/Amount"
},
"creditorAccount": {
"$ref": "#/definitions/Account",
"description": "Creditor Account"
},
"creditorName": {
"type": "string",
"description": "Creditor Name"
},
"debtorId": {
"type": "string",
"description": "Debtor Fiscal Identification Number. Mandatory only for Treasury Payments."
},
"endToEndIdentification": {
"type": "string",
"description": "Transaction Reference"
},
"remittanceInformationUnstructured": {
"type": "string",
"description": "Merchant payment reference"
}
},
"required": [
"instructedAmount",
"creditorAccount",
"creditorName"
]
}
{
"properties": {
"iban": {
"type": "string",
"minLength": 1,
"description": "Account IBAN"
}
},
"additionalProperties": false,
"required": [
"iban"
]
}
{
"properties": {
"currency": {
"type": "string",
"description": "ISO 4217 Alpha 3 currency code"
},
"amount": {
"type": "string",
"description": "The amount given with 2 fractional digits"
}
},
"additionalProperties": false,
"required": [
"currency",
"amount"
]
}
{
"properties": {
"country": {
"type": "string",
"description": "ISO Country Code"
},
"city": {
"type": "string",
"description": "City Name"
},
"street": {
"type": "string",
"description": "Street Name"
},
"buildingNumber": {
"type": "string",
"description": "Builiding Number"
}
},
"additionalProperties": false,
"required": [
"country"
]
}
{
"properties": {
"tppMessages": {
"$ref": "#/definitions/TppMessages"
}
},
"additionalProperties": false
}
{
"type": "array",
"items": {
"$ref": "#/definitions/TppMessage"
}
}
{
"type": "object",
"properties": {
"category": {
"type": "string"
},
"code": {
"type": "string"
},
"text": {
"type": "string"
}
},
"additionalProperties": false
}