Introduction

Overview

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.

Security

Please make sure to read the Security section before proceeding to use this API.

Version

To see the current version and details of recent changes, please see the Changelog.

Interaction

API interaction consists of following mechanisms:

  • Actions - HTTP(s) request initiated by API client (you) and sent to Tribe.
  • Webhooks - HTTP(s) request initiated by Tribe and sent to API client (you).

Actions

This API provides list of actions for retrieving and manipulating data entities.

Workflow for actions is:

bank action diagram

  1. HTTP(s) request (using Request format) must be made to URL.
  2. Response (in Response format) will be returned, indicating success/failure, and providing details.

In order to perform any action, you must use correct:

  • URL
  • Request headers
  • Request format
  • Response format

URL

The URL can be different for each action. It is defined in the description of each action.

Request headers

Required headers can be checked in the Security section.

Request

Request format can be different for each action. It is defined in the description of each action.

Response

Response can be one of 2 types:

  • Success response
  • Error response
Success

Success response format can be different for each action. It is defined in description of each action.

Error

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

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:

bank webhook diagram

In order to see the list of available webhook specifications, please see the Webhooks section.

Request

Request format can be different for each webhook. It is defined in the description of each webhook.

Response

Response can be one of 2 types:

  • Success response
  • Error response
Success

Success response format can be different for each webhook. It is defined in description of each webhook.

Error

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.

Actions

Authorization

Initial

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

Request

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" }

Response

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

"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

Request

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"
  ]
}

Response

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"
}

Revoke token

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

Request

Parameter M Type Length Description
accessToken M AN - Access token used with PSU account(s). 
{
  "accessToken": "defdb58e7a412c74ff9ee692ce9abe3f36d900676edf07ce90cdb30f1529a1e3c0209515a81d2a314f7e740415b1f0fa691e38fecdd380d7d1924f97300aa3232ce1a76e56c59b081e604003a2382b0b67f32500a70cb33af319e4668277a0ad7c72bf8b85708fd530591514d270dd8faa43349d251288ddb6a3a524d0aad6"
}

Response

Parameter M Type Length Description
status M AN 10 Returns success status to acknowledge correct revoke. 
{
  "status": "success"
}

Payment

Payment status

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

Request

Parameter M Type Length Description
paymentId M AN - ID of Payment
paymentStatus M N - Status of Payment 
{
  "paymentId": "8fecdd380d7d1924f97300aa323",
  "paymentStatus": 4
}

Response

Parameter M Type Length Description
status M AN 10 Returns success status to acknowledge correct response. 
{
  "status": "success"
}

Performance

Daily performance

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

Request

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
}

Response

Parameter M Type Length Description
status M AN 10 Returns success status to acknowledge correct response. 
{
  "status": "success"
}

Webhooks

Accounts

Get account list

"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

Request

Empty request.

Response

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

"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

Request

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"
}

Response

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

"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

Request

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"
}

Response

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

"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

Request

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"
}

Response

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"
}

Payments

Single payment

"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

Request

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"
  }
}

Response

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

"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

Request

Parameter M Type Length Description
payment_id M AN 255 Unique payment identifier. 
{
  "payment_id": "4GVDD4545DD"
}

Response

Parameter M Type Length Description
transaction_status M AN 255 Payment status 
{
  "transaction_status": "ACSC"
}

Bulk payment

"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

Request

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"
      }
    }
  ]
}

Response

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

"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

Request

Parameter M Type Length Description
payment_id M AN 255 Unique payment identifier. 
{
  "payment_id": "4GVDD4545DD"
}

Response

Parameter M Type Length Description
transaction_status M AN 255 Payment status 
{
  "transaction_status": "ACSC"
}

Direct Payment

"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

Request

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"
}

Response

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

"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

Request

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"
  }
}

Response

Parameter M Type Length Description
funds_available M B - Boolean indicating presence of funds in the account. 
{
  "funds_available": true
}

Security

Authentication

In order to secure requests these following parameters are used in headers.

Request header

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.

Signature

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
}

Authentication

In order to secure requests the following parameters are used in headers.

Request header

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.

Signature

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
}

Appendix

Changelog

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

Enum

Error code

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

Additional error codes

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

Payment status

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.

Payment schemes

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.

Balance type

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.

Scopes

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

Notation

Abbreviation

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.

Parameter requirement

Notation Description
M Mandatory
O Optional
C Conditional

Type

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)

Workflow

Authorization

Activity

Authorization activity

Sequence

authorization sequence

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.

The workflow of the authorization:

Preconditions: TPP should be already created as a client in the TOB.

  1. User of TPP application accesses BANK authorization website.

  2. The BANK sends the authorization message to TOB.

  3. 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.

  4. The user should be navigated to the authorization in the selected BANK.

  5. Was the authorization successful?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.

  6. Have the PSU approved scopes?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.

    If "yes":

    1. BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.

    2. The BANK redirects the user back to the TPP site with authorization data in URL query.

⚠ Warning!
All the requested consents must be approved: not more and not less. Otherwise, the authorization procedure will not be successful.

Get data

Activity

activity get info

Sequence

get accounts sequence

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.

The workflow of the get info:

  1. BANK receives request to provide PSU data from TOB.

  2. BANK sends the response with the requested information to the TOB.

Payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

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.

Workflow

  1. User of TPP application accesses BANK authorization website.

  2. The BANK sends the authorization message to TOB.

  3. 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.

  4. The user should be navigated to the authorization in the selected BANK.

  5. Was the authorization successful?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.

  6. Have the PSU approved scopes?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.

    If "yes":

    1. BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.

    2. The BANK redirects the user back to the TPP site with authorization data in URL query.

⚠ Warning!
All the requested consents must be approved: not more and not less. Otherwise, the authorization procedure will not be successful.

  1. BANK receives call for payment initiation and performs action necessary to execute payment.

  2. BANK checks if payment can be executed (e.g. balance is enough)?

    If "not":

    1.  BANK cancels the flow, returns error information.

  3. BANK responds with basic payment information and confirmation_url.

  4. User access confirmation_url to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?

    If "no":

    1. The payment will be cancelled, and the user will be redirected back to TPP callback_url and appropriate status and message fields in redirect URL query.

    If "yes":

    1. Payment proceeds and user is redirected back to TPP callback_url with appropriate status, payment_id in redirect URL query.

  5. Was there any reason to decline the payment?

    If "yes":

    1. Flow is canceled, user is redirected back to TPP callback_url with appropriate cancel status, payment_id and message fields in redirect URL query.

Direct payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

Workflow

  1. BANK receives call for payment initiation and performs action necessary to execute payment.

  2. BANK checks if payment can be executed (e.g. balance is enough)?

    If "not":

    1.  BANK cancels the flow, returns error information.

  3. BANK responds with basic payment information and confirmation_url.

  4. User access confirmation_url to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?

    If "no":

    1. The payment will be cancelled, and the user will be redirected back to TPP callback_url and appropriate status and message fields in redirect URL query.

    If "yes":

    1. Payment proceeds and user is redirected back to TPP callback_url with appropriate status, payment_id in redirect URL query.

  5. Was there any reason to decline the payment?

    If "yes":

    1. Flow is canceled, user is redirected back to TPP callback_url with appropriate cancel status, payment_id and message fields in redirect URL query.