This document provides specification of version 2 API endpoints and webhooks for interacting with Tribe Open Banking for ASPSP providers and banks. It allows to integrate REST API in accordance with Payment Service Directive 2 (PSD2) with all required checks.
In order to see procedures flow charts and sequence diagrams, please see the Workflow.
🛈 The terms and their descriptions can be found in the Notation section.
Please make sure to read the Security section before proceeding to use this API.
To see the current version and details of recent changes, please see the Changelog.
API interaction consists of following mechanisms:
This API provides list of actions for retrieving and manipulating data entities.
Workflow for actions is:
In order to perform any action, you must use correct:
The URL can be different for each action. It is defined in the description of each action.
Required headers can be checked in the Security section.
Request format can be different for each action. It is defined in the description of each action.
Response can be one of 2 types:
Success response format can be different for each action. It is defined in description of each action.
Error response is the same for all the actions, and the format is:
Parameter | Requirement | Type | Length | Description |
---|---|---|---|---|
code | M | AN | 255 | Possible error codes Mandatory if any error has occurred. |
title | O | AN | - | Title of the error. |
timestamp | M | AN | 25 | Timestamp of when the error occurred in ISO 8601. |
requestId | M | AN | 16 | UUID of the request. |
additionalErrors | O | LIST | - | List of additional errors . |
additionalErrors[*].code | M | AN | 255 | Possible error codes |
additionalErrors[*].title | O | AN | - | Title of the error. |
additionalErrors[*].details | O | AN | - | Longer description of the error. |
Webhooks are HTTP callbacks triggered by an event in a web application. Open Banking BANK API uses webhooks mainly to pass verified requests from TPP to fetch PSU's data or initiate payment.
Workflow for webhooks:
In order to see the list of available webhook specifications, please see the Webhooks section.
Request format can be different for each webhook. It is defined in the description of each webhook.
Response can be one of 2 types:
Success response format can be different for each webhook. It is defined in description of each webhook.
Error response to webhook request is the same for all the actions, and ASPSP should implement and return it correctly for debugging purposes. The format is:
Parameter | Requirement | Type | Length | Description |
---|---|---|---|---|
code | M | AN | 255 | Mandatory if any error has occurred. |
title | O | AN | - | Title of the error. |
timestamp | M | AN | 25 | Timestamp of when the error occurred in ISO 8601. |
requestId | O | AN | 16 | UUID of the request. |
The "Initial authorization" is the part of the Authorization flow between the BANK and TOB. The BANK sends POST /init_authorization
request to TOB immediately after the user reaches the BANK. The TOB responds with the TPP and necessary consent information and also adds the URL which needs to be used if the BANK does not want to provide the access.
Endpoint | Method |
---|---|
https://bank-api.openbank-sandbox.tribepayments.com/bank/v2/init_authorization | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
requestUrl | M | AN | - | URL with Oauth2 authorization information |
{ "requestUrl": "https://bank.example.com/obb/authorize?client_id=gt34tg3tg34tg&redirect_uri=http%3A%2F%2Ftpp.example.com%2Ftoken&state=1111111&response_type=code&scope=account.list+account.details" }
Parameter | M | Type | Length | Description |
---|---|---|---|---|
tppName | M | AN | - | TPP name |
tppRegistrationNumber | M | AN | - | TPP registration number |
scopes | M | LIST | - | Scopes to be approved |
cancelUrl | M | AN | - | URL for cancelling authorization |
{ "tppName": "TPP name",
"tppRegistrationNumber": "UK-145441",
"scopes": [
"account.list",
"payment.init"
],
"cancelUrl": "https://tpp.example.com/authorize/cancel?hash=JFB45sdasdJHNFDD554" }
"Save consent" is the part of the Authorization flow between the BANK and TOB. BANK sends the request with the consents (scopes) and accounts for which consents were approved. As soon as TOB gets a request from the BANK it responds with the callback URL and generated token.
Endpoint | Method |
---|---|
https://bank-api.openbank-sandbox.tribepayments.com/bank/v2/consent | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
scopes | M | LIST | - | List of approved consents |
requestUrl | M | AN | - | Used authorization URL |
ibans | O | LIST | List of scope approved IBANs | |
accountIds | O | LIST | List of scope approved account IDs | |
accountNumbers | O | LIST | List of scope approved account number (possibly in combination with sort code) |
{
"scopes": [
"payment.init",
"account.list"
],
"requestUrl": "https://bank.example.com/obb/authorize?client_id=gt34tg3tg34tg&redirect_uri=http%3A%2F%2Ftpp.example.com%2Ftoken&state=1111111&response_type=code&scope=account.list+account.details",
"ibans": [
"GB67BARC20037893545993",
"GB66BARC20040438475453",
"GB65BARC20040454867986"
],
"accountIds": [
"6d900676edf07ce90cdb30f1529a1e3c02095"
],
"accountNumbers": [
"123456",
"555987"
]
}
Parameter | M | Type | Description |
---|---|---|---|
callbackUrl | M | AN | Callback URL to redirect the user back to the TPP. |
accessToken | M | AN | A generated token which will be used to access user data. |
validUntil | M | AN | The date until the token will be valid. |
{
"callbackUrl": "https://tpp.example.com/signed",
"accessToken": "$#@%#$%^$@#$56445641653!@#$%3",
"validUntil": "2020-10-13T12:54:58+00:00"
}
In order to revoke PSU token, request with currently used access token is used.
Endpoint | Method |
---|---|
https://bank-api.openbank-sandbox.tribepayments.com/bank/v2/token/revoke | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
accessToken | M | AN | - | Access token used with PSU account(s). |
{
"accessToken": "defdb58e7a412c74ff9ee692ce9abe3f36d900676edf07ce90cdb30f1529a1e3c0209515a81d2a314f7e740415b1f0fa691e38fecdd380d7d1924f97300aa3232ce1a76e56c59b081e604003a2382b0b67f32500a70cb33af319e4668277a0ad7c72bf8b85708fd530591514d270dd8faa43349d251288ddb6a3a524d0aad6"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | AN | 10 | Returns success status to acknowledge correct revoke. |
{
"status": "success"
}
In case of change in payment status, Bank should inform TPP about it by calling this endpoint.
Endpoint | Method |
---|---|
https://bank-api.openbank-sandbox.tribepayments.com/bank/v2/payments/status | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
paymentId | M | AN | - | ID of Payment |
paymentStatus | M | N | - | Status of Payment |
{
"paymentId": "8fecdd380d7d1924f97300aa323",
"paymentStatus": 4
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | AN | 10 | Returns success status to acknowledge correct response. |
{
"status": "success"
}
Bank should inform TOB about daily performance average on consent authorization and payment confirmation flows each day.
Endpoint | Method |
---|---|
https://bank-api.openbank-sandbox.tribepayments.com/bank/v2/daily_performance | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
date | M | AN | - | The specific date for which the duration data is being submitted. |
consentDuration | O | N | - | The average time, in milliseconds, taken for users to confirm consent in the process. |
paymentDuration | O | N | - | The average time, in milliseconds, taken for users to complete the payment confirmation step. |
{
"date": "2023-11-27",
"consentDuration": 51144,
"paymentDuration": 21215
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | AN | 10 | Returns success status to acknowledge correct response. |
{
"status": "success"
}
"Get accounts" is initiated by the request from TPP and it is part of the Get data flow between the BANK and TOB. TPP requests client's accounts information from TOB which requests the information from the BANK.
In the case of multicurrency accounts, the account for each of the currencies associated with the same account identifier (e.g. IBAN) will be returned in the response with a different resource_id
.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_accounts | POST |
Empty request.
Parameter | M | Type | Length | Description |
---|---|---|---|---|
accounts | M | LIST | List of accounts. | |
accounts[*].resource_id | M | AN | - | ID of the account. |
accounts[*].iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
accounts[*].bban | C | AN | 30 | Local ASPSP identifier of the account. |
accounts[*].account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
accounts[*].sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
accounts[*].currency | M | A | 3 | Account currency in ISO 4217 alpha-3 currency code. |
accounts[*].name | O | AN | 3 | Name of the account. |
accounts[*].payment_schemes | O | LIST | - | List of possible Payment Schemes when account is used as debtor during the payment. |
{
"accounts": [
{
"resource_id": "123",
"iban": "GB29NWBK60161331926819",
"bban": "60161331926819",
"currency": "EUR",
"name": "Main EUR account",
"payment_schemes": [
"SCT",
"SCTI"
]
},
{
"resource_id": "456",
"iban": "GB29NWBK60161331926819",
"bban": "60161331926819",
"currency": "GBP",
"name": "Main GBP account"
}
]
}
"Get account" is initiated by the request from TPP and it is part of the Get data flow between the BANK and TOB. TPP requests the client's account information from TOB which requests the information from the BANK.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_account | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
account_id | M | AN | - | ID of the account. Identical to resource_id from the Get account list webhook. |
{
"account_id": "123"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
account | M | OBJECT | Object containing account information. | |
account.resource_id | M | AN | - | ID of the account. |
account.iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
account.currency | M | A | 3 | Account currency in ISO 4217 alpha-3 currency code. |
account.name | O | AN | 3 | Name of the account. |
account.payment_schemes | O | LIST | - | List of possible Payment Schemes when account is used as debtor during the payment. |
{
"account": [
{
"resource_id": "123",
"iban": "GB29NWBK60161331926819",
"bban": "60161331926819",
"currency": "EUR",
"name": "Main account",
"payment_schemes": [
"SCT",
"SCTI"
]
}
]
}
"Get account balances" is initiated by the request from TPP. It is part of the Get data flow between the BANK and TOB. TPP requests the selected account balance information from TOB which requests the information from the BANK.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_account_balances | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
account_id | M | AN | - | ID of the account. Identical to resource_id from the Get account list webhook. |
{
"account_id": "123"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
balances | M | LIST | - | Array containing a list of balances. |
balances[*].balance_amount | M | OBJECT | - | Object with the balance amount and currency. |
balances[*].balance_amount.amount | M | N | - | Amount of funds in the balance. Decimal separator is dot. |
balances[*].balance_amount.currency | M | A | 3 | Account currency in ISO 4217 alpha-3 currency code. |
balances[*].balance_type | M | A | - | Balance type |
{
"balances": [
{
"balance_amount": {
"amount": "123.22",
"currency": "EUR"
},
"balance_type": "interimBooked"
}
]
}
"Get account transactions" is initiated by the request from TPP. It is part of the Get data flow between the BANK and TOB. TPP requests the selected account transaction information from TOB which requests the information from the BANK.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_account_transactions | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
account_id | M | AN | - | ID of the account. Identical to resource_id from the Get account list webhook. |
booking_status | M | A | 7 | Type of transaction to return. Possible values: booked , pending , both . |
page_key | C | AN | - | Value indicating which page to retrieve. Applicable when there is more than one data page available. |
page_size | O | N | 3 | Maximum number of transactions to be shown in the response. The default value is 100 . |
date_from | O | AN | 10 | Filter transactions beginning from a specific date in YYYY-MM-DD format. |
date_to | O | AN | 10 | Filter transactions ending on a specific date in YYYY-MM-DD format. |
{
"account_id": "123",
"booking_status": "booked"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
transactions | M | OBJECT | Object containing a list of account transactions. | |
transactions.booked | M | LIST | List of account transactions that are booked. | |
transactions.booked.transaction_id | O | AN | - | ID of the transaction. |
transactions.booked.creditor_name | O | AN | - | Name of the transaction receiver. |
transactions.booked.creditor_account | O | OBJECT | Account reference of the transaction receiver. | |
transactions.booked.creditor_account.iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
transactions.booked.creditor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
transactions.booked.creditor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
transactions.booked.creditor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
transactions.booked.debtor_name | O | AN | - | Name of the transaction sender. |
transactions.booked.debtor_account | O | OBJECT | Account reference of the transaction sender. | |
transactions.booked.debtor_account.iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
transactions.booked.debtor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
transactions.booked.debtor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
transactions.booked.debtor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
transactions.booked.remittance_information_unstructured | O | AN | 140 | Remittance information in a single string. |
transactions.booked.remittance_information_structured | O | OBJECT | Remittance information with a specified type. | |
transactions.booked.remittance_information_structured.reference | M | AN | 35 | Remittance information. |
transactions.booked.remittance_information_structured.reference_type | M | AN | 35 | Remittance information type. |
transactions.booked.transaction_amount | M | OBJECT | Object with the transaction amount and currency. | |
transactions.booked.transaction_amount.amount | M | N | - | Transaction amount. |
transactions.booked.transaction_amount.currency | M | A | 3 | Transaction currency in ISO 4217 alpha-3 currency code. |
transactions.booked.transaction_amount.value_date | O | AN | 10 | Date in the YYYY-MM-DD format at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit entry. |
transactions.booked.transaction_amount.booking_date | O | AN | 10 | Date when an entry is posted to an account on the ASPSPs books in the YYYY-MM-DD format. |
transactions.pending | M | LIST | List of account transactions that are pending the confirmation. | |
transactions.pending.transaction_id | O | AN | - | ID of the transaction. |
transactions.pending.creditor_name | O | AN | - | Name of the transaction receiver. |
transactions.pending.creditor_account | O | OBJECT | Account reference of the transaction receiver. | |
transactions.pending.creditor_account.iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
transactions.pending.creditor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
transactions.pending.creditor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
transactions.pending.creditor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
transactions.pending.debtor_name | O | AN | - | Name of the transaction sender. |
transactions.pending.debtor_account | O | OBJECT | Account reference of the transaction sender. | |
transactions.pending.debtor_account.iban | C | AN | 34 | IBAN of the account. In the case of some providers, certain accounts can miss this information (e.g., an account for a credit card). |
transactions.pending.debtor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
transactions.pending.debtor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
transactions.pending.debtor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
transactions.pending.remittance_information_unstructured | O | AN | 140 | Remittance information in a single string. |
transactions.pending.remittance_information_structured | O | OBJECT | Remittance information with a specified type. | |
transactions.pending.remittance_information_structured.reference | M | AN | 35 | Remittance information. |
transactions.pending.remittance_information_structured.reference_type | M | AN | 35 | Remittance information type. |
transactions.pending.transaction_amount | M | OBJECT | Object with the transaction amount and currency. | |
transactions.pending.transaction_amount.amount | M | N | - | Transaction amount. |
transactions.pending.transaction_amount.currency | M | A | 3 | Transaction currency in ISO 4217 alpha-3 currency code. |
transactions.pending.transaction_amount.value_date | O | AN | 10 | Date in the YYYY-MM-DD format at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit entry. |
transactions.pending.transaction_amount.booking_date | O | AN | 10 | The Date when an entry is posted to an account on the ASPSPs books in the YYYY-MM-DD format. |
page_key | C | AN | - | Value pointing to the following page. Not provided when there is either one page of data available or the last data page is retrieved. |
{
"transactions": {
"booked": [
{
"transaction_id": "123",
"creditor_name": "John Smith",
"creditor_account": {
"iban": "GB29NWBK60161331926819"
},
"debtor_name": "Jane Doe",
"debtor_account": {
"iban": "GB56NWBK60161331926819"
},
"remittance_information_structured": {
"reference": "ORD123",
"reference_type": "UNSTRUCTURED"
},
"transaction_amount": {
"amount": "123.22",
"currency": "EUR"
},
"value_date": "2022-10-10",
"booking_date": "2022-10-10"
}
],
"pending": []
},
"page_key": "ZDU0N2M0YTVkZTk3NGIxODkxMjNmZWVmYzEwNjQxZDg"
}
"Single payment" is initiated by the request from TPP, which requests TOB to initiate the payment.
TOB requests BANK to initiate the payment and respond with a confirmation_url
to which the user should be redirected to complete the SCA.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_payment_single | POST |
In the case of debtor_account
and creditor_account
, at least one of iban
, bban
or account_number
with sort_code
has to be provided, depending on the payment_scheme
and type of payment that is being initiated.
Parameter | M | Type | Length | Description |
---|---|---|---|---|
payment_scheme | O | A | 5 | Describes what payment scheme is used. See Payment Schemes for possible values. |
debtor_account | O | OBJECT | Identifier of the debtor account. If it's not provided it should be selectable on the SCA page. | |
debtor_account.iban | C | AN | 34 | IBAN of the account. |
debtor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
debtor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
debtor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
debtor_name | O | AN | 70 | Name of debtor/sender. |
creditor_account | O | OBJECT | Identifier of the creditor account. | |
creditor_account.iban | C | AN | 34 | IBAN of the account. |
creditor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
creditor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
creditor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
creditor_name | O | AN | 70 | Name of creditor/receiver. |
remittance_information_unstructured | O | AN | 140 | An unstructured reference of the transaction. |
remittance_information_structured | O | OBJECT | Reference as contained in the structured remittance reference structure. | |
remittance_information_structured.reference | M | AN | 35 | The actual reference. |
remittance_information_structured.reference_type | M | A | 35 | The remittance information type. |
creditor_address | C | OBJECT | Address of the receiving account holder. | |
creditor_address.street_name | O | AN | 70 | Street name. |
creditor_address.building_number | O | AN | - | Building number. |
creditor_address.town_name | O | AN | - | Name of town/city. |
creditor_address.postal_code | O | AN | - | Postal code. |
creditor_address.country | M | A | 2 | Country identifier as defined by ISO 3166-1 alpha-2. |
instructed_amount | M | OBJECT | Object containing the payment amount and currency. | |
instructed_amount.amount | M | N | 70 | Payment amount. The decimal separator is a dot. |
instructed_amount.currency | M | A | 3 | Payment currency in ISO 4217 alpha-3 currency code. |
callback_url | M | AN | - | URL to which the transaction flow shall be redirected after the SCA. |
creditor_bank | C | OBJECT | Information about payment receiver's institution. Mandatory to use with SWIFT payment scheme. | |
creditor_bank.name | M | AN | Name of the institution. | |
creditor_bank.bic | O | AN | Business Identifier Code is an international standard for routing business transactions and identifying business parties. | |
creditor_bank.country | M | AN | 2 | Country identifier as defined by ISO 3166-1 alpha-2. |
{
"payment_scheme": "SCT",
"debtor_account": {
"iban": "NL31INGB7873292649"
},
"debtor_name": "John Smith",
"creditor_account": {
"iban": "GB29NWBK60161331926819"
},
"creditorName": "Jane Doe",
"remittanceInformationUnstructured": "Ref1234",
"creditorAddress": {
"streetName": "Random st.",
"buildingNumber": "22",
"townName": "London",
"postCode": "LE5 2QF",
"country": "GB"
},
"instructedAmount": {
"amount": "123.22",
"currency": "EUR"
},
"callback_url": "http://example.com/payment-confirm",
"creditor_bank": {
"name": "Example bank",
"bic": "FAKEBICX",
"country": "GB"
}
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment Status |
confirmation_url | M | AN | - | The URL to which the user will be redirected to enter their SCA confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
{
"status": "ACTC",
"confirmation_url": "https://bank.example.com/confirm/?code=32321",
"payment_id": "4GVDD4545DD"
}
Callback URL parameters for redirect after user accesses confirmation_url
and BANK performs redirect to callback_url
from request content:
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment status after confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
message | C | AN | - | Message with description in case of error. |
"Get single payment status" is initiated by the request from TPP. It is part of the Get data flow between the BANK and TOB. TPP requests the status of initiated payment from TOB which then requests the information from the BANK.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_payment_single_status | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
payment_id | M | AN | 255 | Unique payment identifier. |
{
"payment_id": "4GVDD4545DD"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
transaction_status | M | AN | 255 | Payment status |
{
"transaction_status": "ACSC"
}
"Bulk payment" is initiated by the request from TPP to TOB to initiate the payment.
TOB requests BANK to initiate a bulk of payments and respond with a confirmation_url
to which the user should be redirected.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_payment_bulk | POST |
In the case of debtor_account
and creditor_account
, at least one of iban
, bban
or account_number
with sort_code
has to be provided, depending on the payment_scheme
and type of payment that is being initiated.
Parameter | M | Type | Length | Description |
---|---|---|---|---|
payment_scheme | O | A | 5 | Describes what payment scheme is used. See Payment Schemes for possible values. |
debtor_account | O | OBJECT | Identifier of the debtor account. If it's not provided it should be selectable on the SCA page. | |
debtor_account.iban | C | AN | 34 | IBAN of the account. |
debtor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
debtor_account.account_number | C | N | 8 | Account Number. Used to identify the account in the United Kingdom. |
debtor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
debtor_name | O | AN | 70 | Name of debtor/sender. |
callback_url | M | AN | - | URL to which the transaction flow shall be redirected after the SCA. |
instructed_totals | M | OBJECT | Contains the total amount of bulk payments. | |
instructed_totals.currency | M | A | 3 | Total amount currency in ISO 4217 alpha-3 currency code. |
instructed_totals.amount | M | N | 10 | Total amount. |
payments | M | LIST | List of individual payments - limited to 1000. | |
payments[*].creditor_account | O | OBJECT | Identifier of the creditor account. | |
payments[*].creditor_account.iban | C | AN | 34 | IBAN of the account. |
payments[*].creditor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
payments[*].creditor_account.account_number | C | N | 8 | Account Number. Used to identify the account in the United Kingdom. |
payments[*].creditor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
payments[*].creditor_name | O | AN | 70 | Name of creditor/receiver. |
payments[*].remittance_information_unstructured | O | AN | 140 | An unstructured reference of the transaction. |
payments[*].remittance_information_structured | O | OBJECT | Reference as contained in the structured remittance reference structure. | |
payments[*].remittance_information_structured.reference | M | AN | 35 | The actual reference. |
payments[*].remittance_information_structured.reference_type | M | A | 35 | The remittance information type. |
payments[*].creditor_address | C | OBJECT | Address of the receiving account holder. | |
payments[*].creditor_address.street_name | O | AN | 70 | Street name. |
payments[*].creditor_address.building_number | O | AN | - | Building number. |
payments[*].creditor_address.town_name | O | AN | - | Name of town/city. |
payments[*].creditor_address.postal_code | O | AN | - | Postal code. |
payments[*].creditor_address.country | M | A | 2 | Country identifier as defined by ISO 3166-1 alpha-2. |
payments[*].instructed_amount | M | OBJECT | Object containing the payment amount and currency. | |
payments[*].instructed_amount.amount | M | N | 70 | Payment amount. The decimal separator is a dot. |
payments[*].instructed_amount.currency | M | A | 3 | Payment currency in ISO 4217 alpha-3 currency code. |
{
"payment_scheme": "SCT",
"callback_url": "http://fake-callback.openbank.com",
"instructed_totals": {
"currency": "EUR",
"amount": "222.4"
},
"payments": [
{
"creditor_account": {
"iban": "NL31INGB7873292649"
},
"creditorName": "Jane Doe",
"remittanceInformationUnstructured": "Ref1234",
"creditorAddress": {
"streetName": "Random st.",
"buildingNumber": "22",
"townName": "London",
"postCode": "LE5 2QF",
"country": "GB"
},
"instructedAmount": {
"amount": "123.22",
"currency": "EUR"
}
}
]
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment Status |
confirmation_url | M | AN | - | The URL to which the user will be redirected to enter their SCA confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
{
"status": "ACTC",
"confirmation_url": "https://bank.example.com/confirm/?code=32321",
"payment_id": "4GVDD4545DD"
}
Callback URL parameters for redirect after user accesses confirmation_url
and BANK performs redirect to callback_url
from request content:
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment status after confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
message | C | AN | - | Message with description in case of error. |
"Get bulk payment status" is initiated by the request from TPP. It is part of the Get data flow between the BANK and TOB. TPP requests the status of initiated payment from TOB which then requests the information from the BANK.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_payment_bulk_status | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
payment_id | M | AN | 255 | Unique payment identifier. |
{
"payment_id": "4GVDD4545DD"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
transaction_status | M | AN | 255 | Payment status |
{
"transaction_status": "ACSC"
}
"Direct payment initiation" is initiated by the request from TPP. TOB requests BANK to initiate the payment and respond with a confirmation_url
to which the user should be redirected.
It is part of the flow where TPP requests TOB to initiate the Direct payment.
The endpoint is almost identical to the payment one. The difference has to do with Security where the X-Auth-Token
header identifying the user is not passed.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_payment_direct_single | POST |
In the case of debtor_account
and creditor_account
, at least one of iban
, bban
or account_number
with sort_code
has to be provided, depending on the payment_scheme
and type of payment that is being initiated.
Parameter | M | Type | Length | Description |
---|---|---|---|---|
payment_scheme | O | A | 5 | Describes what payment scheme is used. See Payment Schemes for possible values. |
debtor_account | O | OBJECT | Identifier of the debtor account. If it's not provided it should be selectable on the SCA page. | |
debtor_account.iban | C | AN | 34 | IBAN of the account. |
debtor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
debtor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
debtor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
debtor_name | O | AN | 70 | Name of debtor/sender. |
creditor_account | O | OBJECT | Identifier of the creditor account. | |
creditor_account.iban | C | AN | 34 | IBAN of the account. |
creditor_account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
creditor_account.account_number | C | N | 8 | Account number. Used to identify the account in the United Kingdom. |
creditor_account.sort_code | C | N | 6 | Sort code. Used to identify the account in the United Kingdom. |
creditor_name | O | AN | 70 | Name of creditor/receiver. |
remittance_information_unstructured | O | AN | 140 | An unstructured reference of the transaction. |
remittance_information_structured | O | OBJECT | Reference as contained in the structured remittance reference structure. | |
remittance_information_structured.reference | M | AN | 35 | The actual reference. |
remittance_information_structured.reference_type | M | A | 35 | The remittance information type. |
creditor_address | C | OBJECT | Address of the receiving account holder. | |
creditor_address.street_name | O | AN | 70 | Street name. |
creditor_address.building_number | O | AN | - | Building number. |
creditor_address.town_name | O | AN | - | Name of town/city. |
creditor_address.postal_code | O | AN | - | Postal code. |
creditor_address.country | M | A | 2 | Country identifier as defined by ISO 3166-1 alpha-2. |
instructed_amount | M | OBJECT | Object containing the payment amount and currency. | |
instructed_amount.amount | M | N | 70 | Payment amount. The decimal separator is a dot. |
instructed_amount.currency | M | A | 3 | Payment currency in ISO 4217 alpha-3 currency code. |
callback_url | M | AN | - | URL to which the transaction flow shall be redirected after the SCA. |
creditor_bank | C | OBJECT | Information about payment receiver's institution. Mandatory to use with SWIFT payment scheme. | |
creditor_bank.name | M | AN | Name of the institution. | |
creditor_bank.bic | O | AN | Business Identifier Code is an international standard for routing business transactions and identifying business parties. | |
creditor_bank.country | M | AN | 2 | Country identifier as defined by ISO 3166-1 alpha-2. |
{
"payment_scheme": "SCT",
"debtor_account": {
"iban": "GB29NWBK60161331926819"
},
"debtor_name": "John Smith",
"creditor_account": {
"iban": "NL31INGB7873292649"
},
"creditorName": "Jane Doe",
"remittanceInformationUnstructured": "Ref1234",
"creditorAddress": {
"streetName": "Random st.",
"buildingNumber": "22",
"townName": "London",
"postCode": "LE5 2QF",
"country": "GB"
},
"instructedAmount": {
"amount": "123.22",
"currency": "EUR"
},
"callback_url": "http://example.com/payment-confirm"
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment Status |
confirmation_url | M | AN | - | The URL to which the user will be redirected to enter their SCA confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
{
"status": "ACTC",
"confirmation_url": "https://bank.example.com/confirm/?code=32321",
"payment_id": "4GVDD4545DD"
}
Callback URL parameters for redirect after user accesses confirmation_url
and BANK performs redirect to callback_url
from request content:
Parameter | M | Type | Length | Description |
---|---|---|---|---|
status | M | A | 4 | Payment status after confirmation. |
payment_id | M | AN | 255 | Unique payment identifier. |
message | C | AN | - | Message with description in case of error. |
"Confirmation of funds" is initiated by the request from TPP. It is part of the Get data flow between the BANK and TOB.
It can be used by CBPII to confirm the amount of funds available in the account. Funds can only be confirmed against the currency of the account. This action does not reserve an amount requested in the account but only indicates if the requested amount is present at the time of the API call.
Endpoint | Method |
---|---|
https://BANK_DOMAIN/v2_funds_confirmations | POST |
Parameter | M | Type | Length | Description |
---|---|---|---|---|
account | M | OBJECT | - | Identifier of the account. |
account.iban | C | AN | 34 | IBAN of the account. |
account.bban | C | AN | 30 | Local ASPSP identifier of the account. |
account.account_number | C | N | 8 | Used to identify the account in United Kingdom. |
account.sort_code | C | N | 6 | Used to identify the account in United Kingdom. |
instructed_amount | M | OBJECT | - | An amount with a currency. |
instructed_amount.amount | M | N | 70 | An amount of the currency. The decimal separator is a dot. |
instructed_amount.currency | M | A | 3 | Currency in ISO 4217 alpha-3 currency code. |
{
"account": {
"iban": "NL33RABO4242739303"
},
"instructed_amount": {
"currency": "EUR",
"amount": "12.5"
}
}
Parameter | M | Type | Length | Description |
---|---|---|---|---|
funds_available | M | B | - | Boolean indicating presence of funds in the account. |
{
"funds_available": true
}
In order to secure requests these following parameters are used in headers.
Key | M | Example | Description |
---|---|---|---|
X-Api-Key | M | a#p#i#k#e#y | Used for client authorization reasons. The API key must match the BANK's client API key. Unique for each BANK provider. |
X-Auth-Token | C | $#s3gS#egD | The token is generated during the authorization procedure after the consents are submitted. Each user has a unique token. Not required when not using user data. Not used for Direct payment. |
X-Request-Id | M | 1af7b333-7a06-41b1-8a61-e9a29fd069bc | Unique request ID - must be valid UUID |
Content-Type | O | application/json |
API uses JSON data format. |
X-Signature | O | d5xbk0uf.....asdlk | Request signed with the Open Banking private key. |
Message integrity is ensured with custom signature header X-Signature
. Signatures are generated with SHA-256 algorithm.
Example of verification:
$verify = openssl_verify(
$requestContent,
base64_decode($signature),
$publicKey,
OPENSSL_ALGO_SHA256
);
if (1 === $verify) {
// signature is correct
}
In order to secure requests the following parameters are used in headers.
Key | M | Example | Description |
---|---|---|---|
X-Api-Key | M | a#p#i#k#e#y | Used for client authorization reasons. The API key must match the BANK's client API key. Unique for each BANK provider. |
X-Auth-Token | C | $#s3gS#egD | The token is generated during the authorization procedure after the consents are submitted. Each user has a unique token. Not required when not using user data. Not used for Direct payment. |
X-Request-Id | M | 1af7b333-7a06-41b1-8a61-e9a29fd069bc | Unique request ID - must be valid UUID. |
Content-Type | O | application/json |
API uses the JSON data format in the request body. |
X-Signature | M | d5xbk0uf.....asdlk | Request signed with the Open Banking private key. |
Message integrity is ensured with the custom signature header X-Signature
. Signatures are generated using the SHA-256 algorithm.
An example of signature verification:
$verify = openssl_verify(
$requestContent,
base64_decode($signature),
$publicKey,
OPENSSL_ALGO_SHA256
);
if (1 === $verify) {
// the signature is correct
}
Version | Date | Updates |
---|---|---|
2.0.1 | May 22, 2024 | Added new endpoints: Init Authorization Save consent Revoke token Payment status Daily performance. Added new Error codes and Additional error codes. |
2.0.0 | June 30, 2023 | Initial version |
Code | Status code | Description |
---|---|---|
INTERNAL_SERVER_ERROR | 500 | Internal error |
PAYMENT_SCHEME_INVALID | 400 | Provided payment scheme is invalid for current ASPSP |
ASPSP_UNKNOWN_ERROR | 502 | Request to ASPSP failed |
PARAMETER_NOT_CONSISTENT | 400 | URL path or query parameter is invalid |
FORMAT_ERROR | 400 | Wrong request content |
HEADERS_ERROR | 400 | Headers error |
SERVICE_BLOCKED | 403 | Access denied |
RESOURCE_UNKNOWN | 404 | Resource unknown |
WRONG_CREDENTIALS | 401 | Wrong credentials |
AUTHENTICATION_REQUIRED | 401 | Authentication required |
API_ACTION_DOES_NOT_EXIST | 401 | This API action does not exist |
SSL_CREDENTIALS_NOT_FOUND | 401 | SSL credentials not found: "SSL_CLIENT_S_DN_Email", "SSL_CLIENT_S_DN" |
REQUEST_ID_NOT_UUID | 401 | Header "X-Request-Id" is not valid UUID |
Code | Description |
---|---|
ASPSP_ERROR_DESC | ASPSP error description |
EXTRA_FIELDS_PROVIDED | Unknown fields provided in the request content |
INVALID_DATE_FORMAT | Invalid "date" format |
INVALID_MODEL_TYPE | Field {{ fieldName }} type is invalid |
INVALID_PAYMENT_ID_FORMAT | Invalid "paymentId" format |
INVALID_PAYMENT_STATUS_FORMAT | Invalid "paymentStatus" format |
AUTHORIZATION_REQUEST_URL_DOES_NOT_EXIST | Parameter "requestUrl" is missing |
AUTHORIZATION_REQUEST_URL_NOT_VALID | Parameter "requestUrl" is not correct |
AUTHORIZATION_SCOPE_DOES_NOT_EXIST | Parameter "scope" is missing |
AUTHORIZATION_SCOPE_NOT_CORRECT | Parameter "scope" is not correct |
AUTHORIZATION_IBAN_NOT_VALID | Parameter "iban" is not correct |
AUTHORIZATION_SELECTED_WRONG_SCOPE | Selected scope is not valid for this request |
AUTHORIZATION_ACCOUNT_IDENTIFIERS_MISSING | Account identifiers missing |
AUTHORIZATION_TOKEN_NOT_VALID | Invalid "accessToken" format |
Status | ISO 20022 string | Description |
---|---|---|
ACCC | AcceptedSettlementCompleted | Settlement on the creditor's account has been completed. This code is not supported by most banks. |
ACCP | AcceptedCustomerProfile | Preceding check of technical validation was successful. The customer profile check was also successful. |
ACSC | AcceptedSettlementCompleted | Settlement on the debtor’s account has been completed. |
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 as well as syntactical and semantical validation are successful. This is usually regarded as a pending status, waiting for SCA. |
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’s 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 updates will be performed. |
RJCT | Rejected | Payment initiation or individual transaction included in the payment initiation has been rejected. |
CANC | Canceled | Payment initiation has been cancelled before execution. |
ACFC | AcceptedFundsChecked | Preceding check of technical validation and customer profile was successful and an automatic funds check was positive. |
PATC | PartiallyAcceptedTechnicalCorrect | The payment initiation needs multiple authentications, where some but not yet all have been performed. Syntactical and semantical validations are successful. |
PART | PartiallyAccepted | A number of transactions have been accepted, whereas a number of other transactions have not yet been granted the 'accepted' status. |
Scheme | Description |
---|---|
FPS | Faster Payments is used for payments between United Kingdom BANKs. Used by default for UK payments. |
BACS | Usable for payments in the United Kingdom. |
CHAPS | Usable for payments in the United Kingdom. |
SCTI | Used for instant SEPA payments if supported by BANKs. |
SCT | Used for SEPA payments. Used as the default for EU payments. |
SWIFT | SWIFT (Society for Worldwide Interbank Financial Telecommunication), used for international and multicurrency payments. |
This definition is following ISO20022 logic for defining balance types.
Type | Description |
---|---|
openingBooked | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. |
interimAvailable | Available balance calculated in the course of the account servicer’s business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. Available balance typically includes credit line. |
interimBooked | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
forwardAvailable | Forward available balance of money that is at the disposal of the account owner on the date specified. |
nonInvoiced | Only for card accounts, to be defined yet. |
Scope | Service | Description |
---|---|---|
accounts | AISP | Get PSU account list and details |
accounts.balances | AISP | Get PSU account's balances |
accounts.transactions | AISP | Get PSU account's transactions |
payments.single | PISP | Single Payment initiation |
payments.bulk | PISP | Bulk Payment initiation |
funds_confirmations | CBPII | Confirmation of funds |
Abbreviation | Description |
---|---|
ASPSP | Account Servicing Payment Service Provider |
BANK | Account Servicing Payment Service Provider (ASPSP) |
AISP | Account Information Service Provider |
PISP | Payment Initiation Service Provider |
CBPII | Card Based Payment Instrument Issuer |
BIC | BANK Identifier Code |
Consent | Consent is the agreement given by the customer to the TPP to retrieve the PSU's data from the BANK. Consent is stored and verified by the BANK, but approved by the PSU. Consent may have different characteristics, like recurrence, expiration, etc. |
PSU | Payment Service User |
SCA | The process of using a strong (2-factor) identification method to identify the customer. |
TOB | Tribe Open Banking |
TPP | Third-Party Provider (TPP) is a provider of an application that the PSU uses and that is not offered by the BANK. TPP is the client/consumer of the API and acts on behalf of the PSU. |
Notation | Description |
---|---|
M | Mandatory |
O | Optional |
C | Conditional |
Notation | Description |
---|---|
A | Alphabetical inputs (A-Z a-z) |
AN | Alphanumeric inputs (0-9 A-Z a-z .!@) |
LIST | |
OBJECT | JSON object |
N | Numeric inputs (0-9) |
Authorization is necessary to provide TPP consents to access accounts and their information in the BANK. As long as consents are valid this procedure will not be repeated, except for the authorization in the payments flow.
Preconditions: TPP should be already created as a client in the TOB.
User of TPP application accesses BANK authorization website.
The BANK sends the authorization message to TOB.
TOB responds with the TPP information, consents that need to be approved, and a URL address in which the user needs to be redirected if the consents will not be provided to TPP.
The user should be navigated to the authorization in the selected BANK.
Was the authorization successful?
If "no":
Have the PSU approved scopes?
If "no":
If "yes":
BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.
The BANK redirects the user back to the TPP site with authorization data in URL query.
Get data flow is necessary for the TPP to retrieve information. The TPP can request PSU accounts list, account details, payment list etc. Access to information depends on which scopes were approved on the BANK side, e.g. if the TPP does not have consent for the account details, account details will no be provided for the TPP. Length of validity is provided in response with access token.
Get data can be initiated without user interaction. The TPP itself can request for the information.
BANK receives request to provide PSU data from TOB.
BANK sends the response with the requested information to the TOB.
Payment flow has 2 variants:
One-time use consent, which requires whole authorization flow, is similar to the authorization flow above, actions are identical up to point 6 and token is expired after use.
Reusable consent which does not expire after single use and can be used for payment repeatedly.
User of TPP application accesses BANK authorization website.
The BANK sends the authorization message to TOB.
TOB responds with the TPP information, consents that need to be approved, and a URL address in which the user needs to be redirected if the consents will not be provided to TPP.
The user should be navigated to the authorization in the selected BANK.
Was the authorization successful?
If "no":
Have the PSU approved scopes?
If "no":
If "yes":
BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.
The BANK redirects the user back to the TPP site with authorization data in URL query.
BANK receives call for payment initiation and performs action necessary to execute payment.
BANK checks if payment can be executed (e.g. balance is enough)?
If "not":
1. BANK cancels the flow, returns error information.
BANK responds with basic payment information and confirmation_url
.
User access confirmation_url
to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?
If "no":
callback_url
and appropriate status
and message
fields in redirect URL query.If "yes":
callback_url
with appropriate status
, payment_id
in redirect URL query.Was there any reason to decline the payment?
If "yes":
callback_url
with appropriate cancel status
, payment_id
and message
fields in redirect URL query.BANK receives call for payment initiation and performs action necessary to execute payment.
BANK checks if payment can be executed (e.g. balance is enough)?
If "not":
1. BANK cancels the flow, returns error information.
BANK responds with basic payment information and confirmation_url
.
User access confirmation_url
to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?
If "no":
callback_url
and appropriate status
and message
fields in redirect URL query.If "yes":
callback_url
with appropriate status
, payment_id
in redirect URL query.Was there any reason to decline the payment?
If "yes":
callback_url
with appropriate cancel status
, payment_id
and message
fields in redirect URL query.