Introduction

Overview

This document provides specification of API endpoints and webhooks for interacting with Tribe Open Banking solution for ASPSP providers and banks. It allows to integrate REST API in accordance with Payment Service Directive 2 (PSD2) with all required checks.

You can find communication descriptions between the BANK and the TOB (Tribe Open Banking) during:

  • Authorization procedure
  • Payment procedure
  • Geting (eg. account data) information from the BANK.

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 appendix Security 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 format
  • Response format

URL

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

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
error_code C N 4 Possible error codes Mandatory if any error occurred.
message C AN - Error message - mandatory if any error occurred.

Webhooks

Webhooks are HTTP callbacks triggered by an event in a web application. Open Banking BANK API uses webhooks to asynchronously let your application know when events happen - like getting the payments list and account balance from the TOB.

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 return it correctly for debugging purposes. The format is:

Parameter Requirement Type Length Description
status M AN 5 Must be error.
error_code C N - Error code defined by ASPSP, used for debugging purposes and communication.
message C AN - Description of error.

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/init_authorization POST

Request

Parameter M Type Length Description
request_url M AN - URL with Oauth2 authorization information 
{  "request_url": "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
tpp_name M AN - TPP name
tpp_registration_number M AN - TPP registration number
scopes M LIST - Scopes to be approved
cancel_url M AN - URL for cancelling authorization 
{  "tpp_name": "TPP name",
   "tpp_registration_number": "UK-145441",  
   "scopes": [  
       "account.list", 
       "payment.init"  
    ],  
   "cancel_url": "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/consent POST

Request

Parameter M Type Length Description
scopes M LIST - List of approved consents
request_url M AN - Used authorization URL
ibans O LIST List of scope approved IBANs
account_ids O LIST List of scope approved account IDs
account_numbers O LIST List of scope approved account number (possibly in combination with sort code) 
{
  "scopes": [
    "payment.init",
    "account.list"
  ],
  "request_url": "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"
  ],
  "account_ids": [
    "6d900676edf07ce90cdb30f1529a1e3c02095"
  ],
  "account_numbers": [
    "123456",
    "555987"
  ]
}

Response

Parameter M Type Description
callback_url M AN Callback URL to redirect the user back to the TPP.
access_token M AN A generated token which will be used to access user data.
valid_until M AN The date until the token will be valid. 
{
  "callback_url": "https://tpp.example.com/signed",
  "access_token": "$#@%#$%^$@#$56445641653!@#$%3",
  "valid_until": "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/token/revoke POST

Request

Parameter M Type Length Description
access_token M AN - Access token used with PSU account(s). 
{
  "access_token": "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/payments/status POST

Request

Parameter M Type Length Description
payment_id M AN - ID of Payment
payment_status M N - Status of Payment 
{
  "payment_id": "8fecdd380d7d1924f97300aa323",
  "payment_status": 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/daily_performance POST

Request

Parameter M Type Length Description
date M AN - The specific date for which the duration data is being submitted.
consent_duration O N - The average time, in milliseconds, taken for users to confirm consent in the process.
payment_duration O N - The average time, in milliseconds, taken for users to complete the payment confirmation step. 
{
  "date": "2023-11-27",
  "consent_duration": 51144,
  "payment_duration": 21215
}

Response

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

Webhooks

Account

Balance

"Get account balance" is initiated by the request from TPP. It is the part of the Get data flow between the BANK and TOB. TPP requests selected account balance information from TOB which requests the information from the BANK. One of iban or account_id have to be provided.

Endpoint Method
https://BANK_DOMAIN/account_balance POST

Request

Parameter M Type Length Description
iban C AN 34 Selected IBAN
account_id C AN 34 Account ID specific for the BANK 
{
  "iban": "GB63BARC20038416599456"
}

Response

Parameter M Type Length Description
status M AN 10 Response status indicator
accounts M LIST Under this parameter all requested accounts will be listed.
id M N 20 The ID of the account
name M AN 20 The name of the account
balance M N 50 Account balance
currency M A 3 Currency abbreviation according to ISO 4217 
{
  "status": "success",
  "account": {
    "id": 15922246314898,
    "name": "John Doe",
    "balance": 5000.00,
    "currency": "EUR"
  }
}

Get account

"Get account" is initiated by the request from TPP. It is the part of the Get data flow between the BANK and TOB. TPP requests selected account information from TOB which requests the information from the BANK. One of iban or account_id have to be provided.

Endpoint Method
https://BANK_DOMAIN/account POST

Request

Parameter M Type Length Description
iban C AN 34 Selected IBAN
account_id C AN 34 Account ID specific for the BANK 
{
  "iban": "GB63BARC20038416599456"
}

Response

Parameter M Type Length Description
status M AN 10 Response status indicator
account M LIST List of accounts
id M N 20 The ID of the account
name M AN 50 The name of the account
iban M AN 34 The IBAN information
currency M A 3 Currency abbreviation according to ISO 4217
additional_data M LIST Listed additional data 
{
  "status": "success",
  "account": {
    "id": 15922246314898,
    "name": "John Doe",
    "iban": "GB63BARC20038416599456",
    "currency": "EUR",
    "additional_data": []
  }
}

Get account list

"Get accounts" is initiated by the request from TPP and it is the 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.

Endpoint Method
https://BANK_DOMAIN/accounts POST

Response

Parameter M Type Length Description
status M AN 10 Response status indicator
accounts M LIST List of accounts
id M N 20 The ID of the account
name M AN 50 The name of the account
iban M AN 34 The IBAN information
currency M A 3 Currency abbreviation according to ISO 4217
additional_data M LIST Listed additional data 
{
  "status": "success",
  "accounts": [
    {
      "id": 15922246314898,
      "name": "John Doe",
      "iban": "GB63BARC20038416599456",
      "currency": "EUR",
      "additional_data": []
    },
    {
      "id": 15922273037137,
      "name": "Jane Doe",
      "iban": "GB52BARC20031856451921",
      "currency": "GBP",
      "additional_data": []
    }
  ]
}

Get payment

"Get account payment" is initiated by the request from TPP. It is the part of the Get data flow between the BANK and TOB. TPP requests selected account payment information from TOB which requests the information from the BANK.

Endpoint Method
https://BANK_DOMAIN/account_payment POST

Request

Parameter M Type Length Description
payment_id M AN 20 Payment identification number 
{
   "payment_id": "15912737323223"
}

Response

As part of additional_data array, any extra fields can be provided by ASPSP and they will passed to TPP.

Parameter M Type Length Description
status M AN 10 Response status indicator
payment M LIST
id M AN 20 The ID of the payment
reference M AN 30 The reference number
date_created M AN 10 ISO 8601 format
amount M N 20 The amount of the payment
status O N 10 The status of the payment.
type O AN 18 Type of transaction - Types
description M AN 255 Information about the transfer
additional_data M LIST
sender_data M LIST
iban C AN 34 The IBAN from which the transfer was made.
account_name C AN 50 The name of the account
account_number C AN 34 The account number
sort_code C AN 6 The sort code
bic C AN 12 BANK identifier code from which the transfer was made.
internal_account_id C AN ID of Account in BANK from which transfer is made.
card_number C N 19 Payment card from which transfer is made.
currency M AN 3 Sender account currency code
receiver_data M LIST
iban C AN 34 The IBAN to which the transfer was made.
account_name C AN 50 The name of the account
account_number C AN 34 The account number
sort_code C AN 6 The sort code
bic C AN 12 BANK identifier code to which the transfer was made.
internal_account_id C AN ID of Account in BANK to which transfer is made.
card_number C N 19 Payment card to which transfer is made.
currency C AN 3 Receiver account currency code 
{
  "status": "success",
  "payment": {
    "id": "15912737323223",
    "reference": "BB210400490",
    "date_created": "2018-04-05",
    "amount": 3500.00,
    "status": 1,
    "description": "Transfer from IBAN (GB52BARC20031856451921) to IBAN (GB79BARC20037841392563)",
    "additional_data": [
      {
        "sender_data": {
          "iban": "GB52BARC20031856451921",
          "account_name": "John Doe",
          "account_number": "4164513165",
          "sort_code": "222444",
          "bic": "TRB00XXX",
          "currency": "EUR"
        },
        "receiver_data": {
          "iban": "GB79BARC20037841392563",
          "account_name": "Jane Doe",
          "account_number": "4165445",
          "sort_code": "111112",
          "bic": "TRB00XXX",
          "currency": "EUR"
        }
      }
    ]
  }
}

Get payments

"Get account payments" is initiated by the request from TPP. It is the part of the Get data flow between the BANK and TOB. TPP requests a selected account payments list with its information from TOB which requests the information from the BANK. One of iban or account_id have to be provided.

Endpoint Method
https://BANK_DOMAIN/account_payments POST

Request

Parameter M Type Length Description
iban C AN 34 International BANK account number
account_id C AN 34 Account ID specific for the BANK
record_count O N 3 Payments count per page - max and default value 100
current_page O N 3 Default value 1 
{
  "iban": "GB79BARC20037841392563",
  "record_count": 15,
  "current_page": 2
}

Response

As part of additional_data array, any extra fields can be provided by ASPSP and they will passed to TPP.

Parameter M Type Length Description
status M AN 10 Response status indicator
payments M LIST
id M AN 20 The ID of the payment
reference M AN 30 The reference number
date_created M AN 10 ISO 8601 format
amount M N 20 The amount of the payment
status O N 10 The status of the payment.
type O AN 18 Type of transaction - Types
description M AN 255 Information about the transfer
additional_data M LIST
sender_data M LIST
iban C AN 34 The IBAN from which the transfer was made.
account_name C AN 50 The name of the account
account_number C AN 34 The account number
sort_code C AN 6 The sort code
bic C AN 12 BANK identifier code from which the transfer was made.
internal_account_id C AN ID of Account in BANK from which transfer is made.
card_number C N 19 Payment card from which transfer is made.
currency M AN 3 Sender account currency code
receiver_data M LIST
iban C AN 34 The IBAN to which the transfer was made.
account_name C AN 50 The name of the account
account_number C AN 34 The account number
sort_code C AN 6 The sort code
bic C AN 12 BANK identifier code to which the transfer was made.
internal_account_id C AN ID of Account in BANK to which transfer is made.
card_number C N 19 Payment card to which transfer is made.
currency M AN 3 Receiver account currency code
paginator M LIST Paginator details
limit M N 3 Current limitation status - max value 100
current_page M N 3 Current listed page 
{
  "status": "success",
  "payments": [
    {
      "id": "15910999261806",
      "reference": "BB200400490",
      "date_created": "2015-12-05",
      "amount": 5500.00,
      "status": 1,
      "type": "Bank transfer",
      "description": "Transfer from IBAN (GB79BARC20037841392563) to IBAN (GB48BARC20039519853282)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB79BARC20037841392563",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          },
          "receiver_data": {
            "iban": "GB48BARC20039519853282",
            "account_name": "Jane Doe",
            "account_number": "1321654",
            "sort_code": "333444",
            "bic": "CCCGB22XXX",
            "currency": "GBP"
          }
        }
      ]
    },
    {
      "id": 15912703821936,
      "reference": "BB200420610",
      "date_created": "2017-05-05",
      "amount": 6500.00,
      "status": 2,
      "description": "Transfer from IBAN (GB79BARC20037841392563) to IBAN (GB91BARC20038082856387)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB79BARC20037841392563",
            "account_name": "Jane Doe",
            "account_number": "1321654",
            "sort_code": "333444",
            "bic": "CCCGB22XXX",
            "currency": "GBP"
          },
          "receiver_data": {
            "iban": "GB91BARC20038082856387",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "paginator": {
    "limit": 15,
    "current_page": 2
  }
}

Payment

Single payment

"Payment initiation" is initiated by the request from TPP. It is the part TPP requests TOB to initiate the payment. TOB requests BANK to initiate the payment and respond with confirmation_url to which user should be redirected.

Endpoint Method
https://BANK_DOMAIN/payment_initiation POST

Request

Parameter M Type Length Description
sender_iban C AN 34 IBAN of sender account, if SCA implementation selects account on payment confirmation, field can be omitted.
amount M N 10 Payment amount
currency M AN 3 Currency abbreviation according to ISO 4217
reference O AN 18 Payment identification
receiver_name M A 40 Name of the receiver
receiver_iban C AN 34 If receiver_iban is provided - receiver_account_number and receiver_sort_code fields can be empty.
receiver_account_number C N 34 Required if the receiver_iban is empty.
receiver_sort_code C AN 6 Required if the receiver_iban is empty.
message_for_receiver O AN 35
callback_url M AN - Callback URL to the TPP
payment_scheme M AN Specifies method of transfer for certain markets/banks. List of schemes.
receiver_address O OBJECT Address object
street_name O AN 50 Street name
building_number O AN 5 House number
town_name O A 50 City name
post_code O AN 10 Postal code
country O A 3 ISO 3166 - alpha-3 
{
  "sender_iban": "GB07BARC20040143155262",
  "amount": 1500.00,
  "currency": "EUR",
  "receiver_name": "Company Ltd",
  "receiver_account_number": "00000014",
  "receiver_sort_code": "040472",
  "message_for_receiver": "Payment for goods",
  "callback_url": "https://tpp.example.com/",
  "payment_scheme": "FPS",
  "receiver_address": {
    "street_name": "Main st.",
    "building_number": "45B",
    "town_name": "London",
    "post_code": "TS21 2BY",
    "country": "GBR"
  }
}

Response

Parameter M Type Description
status M AN Response status indicator
confirmation_url M AN The URL to which the user will be redirected to enter his confirmation.
payment_id M AN Unique payment identifier 
{
  "status": "success",
  "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 N - Status of payment after confirmation.
payment_id M AN - ID of payment
message C AN - Message with description in case of error.

Bulk payment

"Bulk payment" is initiated by the request from TPP. It is the part TPP requests TOB to initiate the payment. TOB requests BANK to initiate bulk of payments and respond with confirmation_url to which user should be redirected.

Endpoint Method
https://BANK_DOMAIN/bulk_payment_initiation POST

Request

Parameter M Type Length Description
sender_iban M AN 34
callback_url M AN - Callback URL to the TPP
totals M LIST List of total amounts in payments
totals / currency M A 3 ISO 4217
totals / amount M N 10 Total amount
payments M LIST List of individual payments - limited to 1000
amount M N 10
receiver_name M A 40
currency M A 3 ISO 4217 - must match the sender_iban account's currency.
receiver_iban C AN 34 If receiver_iban is provided - receiver_account_number and receiver_sort_code fields can be empty.
receiver_account_number C N 34 Required if the receiver_iban is empty.
receiver_sort_code C AN 6 Required if the receiver_iban is empty.
message_for_receiver O AN 35
payment_scheme M AN Specifies method of transfer. List of schemes.
reference C AN 18 Payment identification
receiver_address O OBJECT Address object
street_name O AN 50 Street name
building_number O AN 5 House number
town_name O A 50 City name
post_code O AN 10 Postal code
country M A 2 ISO 3166 - alpha-2 
{
  "sender_iban": "NL09RABO1208552090",
  "callback_url": "http://fake-callback.openbank.com",
  "totals": [
    {
      "currency": "EUR",
      "amount": 222.4
    }
  ],
  "payments": [
    {
      "amount": 122.2,
      "receiver_name": "John Smith",
      "currency": "EUR",
      "receiver_iban": "NL52ABNA5157915454",
      "reference": "payment reference",
      "payment_scheme": "SCT",
      "receiver_address": {"country": "NL"}
    },
    {
      "amount": 100.2,
      "receiver_name": "John Doe",
      "currency": "EUR",
      "receiver_iban": "NL57ABNA7794745128",
      "reference": "payment reference",
      "payment_scheme": "SCT",
      "receiver_address": {"country": "NL"}
    }
  ]
}

Response

Parameter M Type Description
status M AN Response status indicator
confirmation_url M AN The URL to which the user will be redirected to enter his confirmation.
payment_id M AN Unique payment identifier 
{
  "status": "success",
  "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 N - Status of payment after confirmation.
payment_id M AN - ID of payment
message C AN - Message with description in case of error.

Direct Payment

"Direct payment initiation" is initiated by the request from TPP. TOB requests BANK to initiate the payment and respond with confirmation_url to which user should be redirected. It is the part TPP requests TOB to initiate the Direct payment. The endpoint is almost identical to payment, the difference is in Security when X-Auth-Token header identifying user is not passed.

Endpoint Method
https://BANK_DOMAIN/direct_payment_initiation POST

Request

Parameter M Type Length Description
amount M N 10 Payment amount
currency M AN 3 Currency abbreviation according to ISO 4217
reference O AN 18 Payment identification
receiver_name M A 40 Name of the receiver
receiver_iban C AN 34 If receiver_iban is provided - receiver_account_number and receiver_sort_code fields can be empty.
receiver_account_number C N 34 Required if the receiver_iban is empty.
receiver_sort_code C AN 6 Required if the receiver_iban is empty.
message_for_receiver O AN 35
callback_url M AN - Callback URL to the TPP
payment_scheme M AN Specifies method of transfer for certain markets/banks. List of schemes.
receiver_address O OBJECT Address object
street_name O AN 50 Street name
building_number O AN 5 House number
town_name O A 50 City name
post_code O AN 10 Postal code
country O A 3 ISO 3166 - alpha-3 
{
  "amount": 1500.00,
  "currency": "EUR",
  "receiver_name": "Company Ltd",
  "receiver_account_number": "00000014",
  "receiver_sort_code": "040472",
  "message_for_receiver": "Payment for goods",
  "callback_url": "https://tpp.example.com/",
  "payment_scheme": "FPS",
  "receiver_address": {
    "street_name": "Main st.",
    "building_number": "45B",
    "town_name": "London",
    "post_code": "TS21 2BY",
    "country": "GBR"
  }
}

Response

Parameter M Type Description
status M AN Response status indicator
confirmation_url M AN The URL to which the user will be redirected to enter his confirmation.
payment_id M AN Unique payment identifier 
{
  "status": "success",
  "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 N - Status of payment after confirmation.
payment_id M AN - ID of payment
message C AN - Message with description in case of error.

Authorization

Revoke token

In case of revoked token for a PSU, Bank client application is informed by specifiying currently valid access token.

Endpoint Method
https://BANK_DOMAIN/revoke_token POST

Request

Parameter M Type Length Description
access_token M AN - Latest valid access token used with PSU consent.

Response

Client application acknowledges receiving revoke of token by 200 OK HTTP response and successful status.

Parameter M Type Length Description
status M AN - Returns the status of the request: whether it was successful or if any errors have occurred. 
{
  "status": "success"
}

Card based

Confirmation of funds

"Confirmation of funds" is initiated by the request from TPP. It is the part of the Get data flow between the BANK and TOB.

It can be used by CBPII to confirm the amount of funds is available in the account. Funds can only be confirmed against the currency of the account. This action does not reserve amount request in the account, but only indicates if requested amount is present at the time of API call.

Endpoint Method
https://BANK_DOMAIN/funds_confirmations POST

Request

Parameter M Type Length Description
account M OBJECT - Containing data for which request is executed.
account / iban C AN 34 IBAN of the account, need to be specified if account_id is not.
account / account_id C AN 20 ID of account, need to be specified if iban is not.
instructed_amount M OBJECT - Containing amount and currency
instructed_amount / amount M N 10 Amount of funds which are being confirmed.
instructed_amount / currency M A 3 ISO 4217 
{
  "account": {"iban": "NL33RABO4242739303"},
  "instructed_amount": {
    "currency": "EUR",
    "amount": 12.5
  }
}

Response

Either funds_available boolean flag indicating presence of funds in account needs to be returned, or BANK returns both currency and balance and TOB performs calculation if indicated amount is present in account or not.

Parameter M Type Length Description
funds_available C B - Boolean indicating presence of funds in the account.
currency C A 3 Currency of account
balance C N 10 Current balance of account 
{
  "funds_available": true
}

Authorization

Revoke token

In case of revoked token for a PSU, Bank client application is informed by specifiying currently valid access token.

Endpoint Method
https://BANK_DOMAIN/revoke_token POST

Request

Parameter M Type Length Description
access_token M AN - Latest valid access token used with PSU consent.

Response

Client application acknowledges receiving revoke of token by 200 OK HTTP response and successful status.

Parameter M Type Length Description
status M AN - Returns the status of the request: whether it was successful or if any errors have occurred. 
{
  "status": "success"
}

Appendix

Changelog

Version Date Updates
1.1.5 December 20, 2023 Added new endpoint Daily performance.
1.1.4 January 20, 2023 Added error code 4210 - Payment not found.
1.1.3 January 16, 2023 Removed error code 4205 - Unique consent state.
1.1.2 August 10, 2022 Added error code 4007 - TPP client not found.
1.1.1 August 10, 2022 Added error code 4006
1.1.0 January 7, 2022 Added CBPII webhooks - Card based
1.0.1 December 7, 2021 Added Not unique consent error code
1.0.0 August 14, 2020 Initial version

Enum

Error code

Code Description
4000 Unknown error
4001 Wrong request content
4002 Internal server error
4003 Request body is not valid JSON.
4004 Unknown bank
4005 Unreachable TPP
4006 Request to TPP failed.
4007 TPP client not found.
4200 Wrong credentials
4201 Authentication required
4202 Access token not found.
4202 This API action does not exist.
4203 SSL credentials not found: "SSL_CLIENT_S_DN_Email", "SSL_CLIENT_S_DN"
4204 Header "X-Request-Id" is not valid UUID
4210 Payment not found.
4300 Parameter "request_url" is missing.
4301 Parameter "request_url" is not correct.
4302 Parameter "scope" is missing.
4303 Parameter "scope" is not correct.
4305 Parameter "iban" is not correct.
4306 Selected scope is not valid for this request.
4307 Account identifiers missing.

Payment types

Type
Bank transfer
Card transfer
Internal transfer
Load
Withdrawal
Other

Payment status

Status ID Description
0 Unknown
1 Pending
2 Failed
3 Cancelled
4 Confirmed

Payment schemes

Scheme Description
FPS FasterPayment - used for payments between Great Britain BANKs. Used by default for GB payments.
BACS Usable for payments in Great Britain.
CHAPS Usable for payments in Great Britain.
SCTI Used for instant SEPA payments if supported by BANKs.
SCT Used for SEPA payments. Used as default for EU payments.

Possible scope

Scope Service Description
account.list AISP Get PSU accounts list.
account.balance AISP Get PSU account balance.
account.details AISP Get PSU account detailed information.
account.payments AISP Get PSU account payments list.
account.payment AISP Get PSU account payment details.
payment.init PISP Payment initiation
card_based.funds_confirmations CBPII Confirmation of funds

Example

Initial authorization

/**
 * Init authorization call to Open Banking API, sends request data back to the BANK.
 */
if (!empty($_SERVER['request_url'])) {
    $ch = curl_init("/authorization");                                                                      
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $_SERVER['request_url']);                                                                  
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 300);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [                                                                          
        'Content-Type: application/json',                                                                                
        'Content-Length: ' . strlen($_SERVER['request_url'])]                                                                       
    );
    $response = curl_exec($ch);
    curl_close($ch);

    //redirects user to Open Banking login window with response parameters and requestUrl parameter 
}

Possible workflow after logging in

 if (!empty($_POST)) {
    show_consent($_POST['scopes']); //displays user to which information user will grant access for each selected accounts
    if ('success' === $login && !empty($selected_accounts) && $consent_approved_by_user && $key_code_correct) {
        save_consent_and_ibans($selected_accounts, $consent_data); //saves on BANK side. accountIban -> consent. save_consent api call

        $request_params = [
            'scopes' => explode(' ', $_POST['scopes']), //toArray
            'request_url' => $_POST['request_url'],
            'ibans' => $selected_accounts
        ];

        $response = post('/bank/consent', $request_params); //call to Tribe BANK API
        save_user_token($user_id, $response['token']); //saves on the BANK side. userId -> token
        redirect_user($response['callback_url']);
    }
}

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
}

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