Introduction

Overview

This document provides specification of API endpoints and webhooks for interacting with Tribe Open Banking solution. It allows Third Party Providers (TPPs) to interact with partner banks and other providers in accordance with Payment Service Directive 2 (PSD2).

Users of TPP applications (PSU) can grant access to their account and payments data in the partner ASPSPs, which TPP application can then access and use through unified REST API interfaces.

Main focus points of this documentation are: * Securing of API calls to ensure only authorized TPP providers can access API. * Authorization process for user using Oauth2. * Account and payments information API endpoints.

To see procedure flow charts and sequence diagrams that describe API flows, please see the Workflow.

🛈 The terms and their descriptions can be found in the Notation section, additionally, a QSEAL certificate example which can be used in Sandbox version of this API can be found in the Certificate example 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:

tpp 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 the 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 with description of error

Direct actions

Some supported ASPSP provide more direct approach to some actions. Instead of retrieving previous user consent, actions can be executed directly, followed by SCA confirmation in next step. Direct action security is also different from usual action Security

Workflow for direct actions is similar to actions:

tpp 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 the 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 with description of error

Webhooks

Webhooks are HTTP callbacks triggered by an event in a web application. Tribe Open Banking TPP API uses webhooks to asynchronously let your application know when events happen - eg. revoking consent for access token.

Workflow for webhooks:

tpp webhook diagram

In order to see the list of available webhook specifications, please see the Webhooks section. For correctly receiving webhook actions, TPP client application needs to have specified webhook URL.

Each webhook action specifies itself by adding suffix to path part of URL.

Actions

Account

Balance

"Get account balance" action is initiated by the TPP and it is the part of the Get data flow. The account.balance consent (scope) needs to be approved to get the successful response.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/{iban}/balance GET

Request

Parameter M Type Length Description
iban M AN 34 The selected account IBAN number for which the information should be received.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/GB30MOOW00993558881147/balance

Response

Parameter M Type Length Description
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
{
  "id": 15922246314898,
  "name": "John Doe",
  "balance": 5000.00,
  "currency": "EUR"
}

Get

"Get account" action is initiated by the TPP and it is the part of the Get data flow. The account.details consent (scope) needs to be approved to receive a successful response.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/{iban} GET

Request

Parameter M Type Length Description
iban M AN 34 The selected account IBAN number for which the information should be received.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/GB30MOOW00993558881147 

Response

Parameter M Type Length Description
id M N 20 The ID of the account
name M AN 50 The name of the account
currency M A 3 Currency abbreviation according to ISO 4217
additional_data M LIST Listed additional data
{
  "id": 15922246314898,
  "name": "John Doe",
  "currency": "EUR",
  "additional_data": []
}

Get list

"Get accounts" message is initiated by the TPP and it is the part of the Get data flow. The account.list consent (scope) needs to be approved to receive a successful response.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts GET

Request

No parameters required.

Response

Parameter M Type Length What it means
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 C AN 34 The IBAN information, in case of some providers certain accounts can miss this information (eg. account for credit card)
currency M AN 3 Currency abbreviation regarding ISO 4217
additional_data M LIST Listed additional data
{
  "accounts": [
    {
      "id": 15922246314898,
      "name": "John Doe",
      "iban": "GB30MOOW00993558881147",
      "currency": "EUR",
      "additional_data": []
    },
    {
      "id": 15922273037137,
      "name": "Jane Doe",
      "iban": "GB37BARC20040159925731",
      "currency": "EUR",
      "additional_data": []
    }
  ]
}

Get payment

"Get account payment" message is initiated by the TPP and it is the part of the Get data flow. The account.payment consent (scope) needs to be approved to receive a successful response.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/payments/{payment_id} GET

Request

Parameter M Type Length Description
payment_id M AN 20 Payment identification number for which details are requested.

Response

Parameter M Type Length Description
payment M LIST
id M AN 20 The ID of the payment
reference O AN 30 The reference number in case payment contains it
date_created C AN 10 ISO 8601 format, return of value may depend on Bank execution
amount M N 20 The amount of the payment
status O N 10 The status of the payment.
description M AN 255 Information about the transfer
additional_data M LIST
sender_data C OBJECT Return of values may depend on specific bank implementation
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.
currency C AN 3 Sender account currency code
receiver data C OBJECT Return of values may depend on specific bank implementation
iban C AN 34 The IBAN to which the transfer was made.
account_name M AN 50 The name of the account
account_number M AN 34 The account number
sort_code M AN 6 The sort code
bic M AN 12 BANK identifier code to which the transfer was made.
currency M AN 3 Receiver account currency code
{
  "payment": {
    "id": "15912737323223",
    "reference": "BB210400490",
    "date_created": "2018-04-05",
    "amount": 3500.00,
    "status": 1,
    "description": "Transfer from IBAN (GB37BARC20040159925731) to IBAN (GB60BARC20032625475925)",
    "additional_data": [
      {
        "sender_data": {
          "iban": "GB37BARC20040159925731",
          "account_name": "John Doe",
          "account_number": "4164513165",
          "sort_code": "222444",
          "bic": "TRB00XXX",
          "currency": "EUR"
        },
        "receiver_data": {
          "iban": "GB60BARC20032625475925",
          "account_name": "Jane Doe",
          "account_number": "4165445",
          "sort_code": "111112",
          "bic": "TRB00XXX",
          "currency": "EUR"
        }
      }
    ]
  }
}

Get payments

"Get account payments" action is initiated by the TPP and it is the part of the Get data flow. The account.payments consent (scope) needs to be approved to receive the successful response.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/{iban}/payments GET

Request

Parameter M Type Length Description
iban M AN 34 Account IBAN number
page O N 3 Default value - 1
limit O N 3 Payment count per page - default and max values are 100.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/accounts/GB60BARC20032625475925/payments?limit=15&page=2

Response

Parameter M Type Length Description
payments M LIST
id M N 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.
currency M A 3 ISO 4217 format
description M AN 255 Information about the transfer
additional_data M LIST
sender_data C OBJECT Return of values may depend on specific bank implementation
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.
currency C AN 3 Sender account currency code - ISO 4217 format
receiver_data C OBJECT Return of values may depend on specific bank implementation
iban C AN 34 The IBAN to which the transfer was made.
account_name C AN 6 The name of the account
account_number C AN 12 The account number
sort_code C AN 3 The sort code
bic C AN BANK identifier code to which the transfer was made.
currency C AN 3 Receiver account currency code - ISO 4217 format
paginator M LIST Paginator details
page M N 3 Current page of returned results
limit M N 3 Current limit per page - default and max is 100.
{
  "payments": [
    {
      "id": "15910999261806",
      "reference": "BB200400490",
      "date_created": "2015-12-05",
      "amount": 5500.00,
      "status": 1,
      "currency": "EUR",
      "description": "Transfer from IBAN (GB60BARC20032625475925) to IBAN (GB92BARC20031882539351)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB60BARC20032625475925",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          },
          "receiver_data": {
            "iban": "GB92BARC20031882539351",
            "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,
      "currency": "EUR",
      "description": "Transfer from IBAN (GB92BARC20031882539351) to IBAN (GB60BARC20032625475925)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB92BARC20031882539351",
            "account_name": "Jane Doe",
            "account_number": "1321654",
            "sort_code": "333444",
            "bic": "CCCGB22XXX",
            "currency": "GBP"
          },
          "receiver_data": {
            "iban": "GB60BARC20032625475925",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "paginator": {
    "page": 2,
    "limit": 15
  }
}

Authorization

Initial

Action can be used to start Authorization (OAuth 2.0) and retrieve the ASPSP authorization URL to which the PSU should be navigated to make its authorization of account access.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/authorize POST

Request

Parameter M Type Length Description
bic M AN 11 The selected BANK identifier code to which PSU wants to authorize.
scope M AN 256 OAuth2.0 standard defined scope
state O AN 256 OAuth2.0 standard defined state - can be automatically generated.
code_challenge O AN 256 Optional code_challenge in case of using OAuth2.0 authorization code flow with PKCE.
code_challenge_method O AN 44 Only SHA256 method is supported - S256.
{
  "bic": "AAAAAA00000",
  "scope": "account.list payment.details"
}

Response

Parameter M Type Length Description
redirect_url M AN - The redirect URL address to which the PSU should be navigated by the TPP.
{
  "redirect_url": "http://bank.example.com/authorize?client_id=fer848547&redirect_uri=http%3A%2F%2Ftpp.example.com%2Ftoken&state=111111&response_type=code&scope=account.list+account.details"
}

Token

Allows to get access/refresh tokens, which should be used in further requests for getting account information or making payments for the respective PSU. Authorization code has to be sent to receive following tokens. The message is part of the Authorization flow.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/token POST

Request

Parameter M Type Length Description
grant_type M AN 256 OAuth grant type - Possible values: authorization_code or refresh_token
client_id M AN 256 ID of Oauth client
code C AN 256 Authorization code - required when grant_type = authorization_code
refresh_token C AN 256 Required when grant_type = refresh_token
code_verifier C AN 256 Required when grant_type = authorization_code with PKCE extension
{
    "client_id": "6f315407a6e2cd96d4a570f1fe",
    "code": "9aa89b3c8df12f45386c0c901987a092ad5ddc1aab17fd7cac9f55a5908f73847bcbd681",
    "grant_type": "authorization_code"
}

Response

Parameter M Type Length Description
token_type M A 255 Type of authentication scheme
access_token M AN 255 Access token value
expires_in M N 11 Expiration of access token in seconds
refresh_token C AN 255 Refresh token value. Provided when grant_type is application_code and the client application is not registered for persistent token.
refresh_token_expires_in C N 11 Expiration of refresh_token in seconds. Provided when grant_type is application_code and the client application is not registered for persistent token.
scope C AN 255 The list of allowed scopes. Will be provided when grant_type is application_code.
{
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJub25jZSI6ImY0NmM0ZjNlODU2NGFlOTQyNmNkN2JmN2UxYzQ2N2MzIiwiY2xpZW50X2lkIjoiMzRldGYzNGVydGczIiwiZXhwIjoxNjA2ODA4NzgyfQ.ZMnkrKR1uoJdVIiwpQO5XzktFj56y-LgbCuk9mZig1KbQa3U_D8NrBMaBvP2wAIsFKcElYsF5FIy4pxguFmX6w",
    "expires_in": 1800,
    "scope": "account.list account.details account.balance account.payments account.payment payment.init payment.list"
}

Revoke token

In order to revoke PSU token by TPP, request with currently used access token is used.

Endpoint Method
https://bank-api.openbank-sandbox.tribepayments.com/tpp/token/revoke POST

Request

Parameter M Type Length Description
access_token M AN - Access token used with PSU account(s).
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJub25jZSI6IjZkN2QwMWZmMWNhNTJmZDQxNDYyOWMwODE1NTNjMzAzIiwiY2xpZW50X2lkIjoiNDI5ZTU2Y2JiNzU4YWVmMmJhMTY3OWJmNTM2NjY3NWIiLCJleHAiOjE2MTYwNTA1NjB9.beABDfYXqTdErda5afU4xR91ro9k8noNet1D65QOBCNIuTgix4He1Y-z2yaMX0iVHp8vRtgVEyvM5S56u9Do_A"
}

Response

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

Bank

Get list

Action can be used for TPP to get the list of BANKS (with identifiers) that are integrated with the TOB.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/banks GET

Request

Parameter M Type Description
limit O AN Default value - 100
page O AN Current page of returned results
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/banks?limit=100&page=1

Response

Parameter M Type Length Description
banks M LIST - List of BANK objects
banks / identifier M AN 11 Identifier - usually BIC
banks / title M AN TEXT BANK name
{
  "banks": [
    {
      "identifier": "BARCGB22XXX",
      "title": "First bank"
    },
    {
      "identifier": "DEUTDEFFXXX",
      "title": "Second bank"
    }
  ]
}

Banks' scopes

If the TPP needs to, it can request the list of available scopes that can be approved in order to get the access to the required information. The message is optional part of the Authorization flow.

In order to find headers that must be included in request, please see the Authentication.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/banks/{bic}/scopes GET

Request

Parameter M Type Length Description
bic M AN 11 The selected BANK identification code to which PSU wants to authorize.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/banks/AAAAAA00000/scopes

Response

Parameter M Type Length Description
scope M LIST Possible scopes
{
  "scope": "account.list account.details account.balance account.payment"
}

Payment

Initiate

"Payment initiate" action is initiated by the TPP and it is the part of the payment flow. The payment.init consent (scope) needs to be approved to receive a successful response.

In order to find headers that must be included in request, please see the Authentication.

In callback_url query to which PSU is redirected after payment confirmation, additional parameters indicating status and payment_id (optionally message) are added. This can be used to indicate if payment was confirmed successfully.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/payments/init POST

Request

Parameter M Type Length Description
sender_iban C AN 34 If ASPSP SCA implementation selects account on payment confirmation, field can be omitted.
amount M N 10
receiver_name M A 40
currency M A 3 ISO 4217 - must match the sender_iban account's currency.
reference C AN 18 Payment identification
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
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": "GB19BARC20038039451541",
  "amount": 1500.00,
  "receiver_name": "Company Ltd",
  "receiver_account_number": "12345678",
  "receiver_sort_code": "098765",
  "currency": "EUR",
  "reference": "BB46DS542136",
  "receiver_address": {
    "street_name": "Main st.",
    "building_number": "1",
    "town_name": "London",
    "post_code": "SE1 9SG",
    "country": "GBR"
  }
}

Response

Parameter M Type Length Description
request_url M AN - Redirect URL for PSU to access login page.
payment_id M AN 256 Payment ID
{
  "request_url": "http://example.com/en/obb/payment/gef14ge5gfw65get5nyfg5",
  "payment_id": "sdfdsf324514asdf"
}

Callback URL parameters:

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 actions

Initiate

"Payment initiate" action is initiated by the TPP and it is the part of the Direct_payment flow.

In order to find headers that must be included in request, please see the Direct authentication.

In callback_url query to which PSU is redirected after payment confirmation, additional parameters indicating status and payment_id (optionally message) are added. This can be used to indicate if payment was confirmed successfully.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/direct/payments/init/{bank_identifier} POST

Request

URL parameter:

Parameter M Type Length Description
bank_identifier M AN 34 Identifier of ASPSP which is used to execute payment. Usually BIC.

Content parameters:

Parameter M Type Length Description
sender_iban C AN 34 If ASPSP SCA implementation selects account on payment confirmation, field can be omitted.
amount M N 10
receiver_name M A 40
currency M A 3 ISO 4217 - must match the sender_iban account's currency.
reference C AN 18 Payment identification
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
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": "GB19BARC20038039451541",
  "amount": 1500.00,
  "receiver_name": "Company Ltd",
  "receiver_iban": "GB67BARC20040438716868", 
  "currency": "EUR",
  "reference": "BB46DS542136"
}

Response

Parameter M Type Length Description
request_url M AN - Redirect URL for PSU to access login page.
payment_id M AN 256 Payment ID
{
  "request_url": "http://example.com/en/obb/payment/gef14ge5gfw65get5nyfg5",
  "payment_id": "sdfdsf324514asdf"
}

Callback URL parameters:

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.

Webhooks

Following actions apply in case TPP client has specified webhook URL. Actions are called only if TPP client has webhook URL specified.

Payment status

TPP client application is informed by specifying the payment status is changed, and the TPP should respond that they have received the webhook successfully.

Endpoint Method
https://TPP_DOMAIN/webhook-base-uri/payment_status POST

Request

Parameter M Type Length Description
payment_id M N 11 Unique payment identifier. The max length of the field is 20 characters.
bank_identifier M AN - Identifier of Bank
payment_status M N 20 See Payment status.
{
  "payment_id": "454651545114",
  "bank_identifier": "TRB00XXX",
  "payment_status": 3
}

Response

Parameter M Type Length Description
status M AN 10 Brings back if the request was successful or there were any errors.
{
  "status": "success"
}

Revoke token

In case of revoked token for a PSU, TPP client application is informed by specifying currently valid access token and additionally refresh token if applicable.

Endpoint Method
https://TPP_DOMAIN/webhook-base-uri/revoke_token POST

Request

Parameter M Type Description
access_token M AN Latest valid access token used with PSU consent.
refresh_token C AN Refresh token assigned with PSU consent if client application is using rotating access tokens.

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.0.0 August 19, 2020 Initial version

Enum

Certificate example

For testing purposes in Sandbox API version you can use this QSEAL Certificate in the Tpp-Signature-Certificate header:

MIIF3DCCA8SgAwIBAgIUNZWnH8t06DeVnD8M9fc6A7MfGVYwDQYJKoZIhvcNAQEL
BQAwgbMxCzAJBgNVBAYTAkdCMQ8wDQYDVQQIDAZMb25kb24xDzANBgNVBAcMBkxv
bmRvbjEZMBcGA1UECgwQVHJpYmVQYXltZW50cyBDQTEZMBcGA1UECwwQT3BlbmJh
bmtpbmcgVGVhbTElMCMGA1UEAwwcVHBwU2FuZGJveCBRc2VhbCBDZXJ0aWZpY2F0
ZTElMCMGCSqGSIb3DQEJARYWaW5mb0B0cmliZXBheW1lbnRzLmNvbTAgFw0yMTAx
MTMxMjQ3NDJaGA8yMTIwMTIyMDEyNDc0MlowgcsxCzAJBgNVBAYTAkdCMQ8wDQYD
VQQIDAZMb25kb24xDzANBgNVBAcMBkxvbmRvbjEWMBQGA1UECgwNVHJpYmVQYXlt
ZW50czEZMBcGA1UECwwQT3BlbmJhbmtpbmcgVGVhbTElMCMGA1UEAwwcVHBwU2Fu
ZGJveCBRc2VhbCBDZXJ0aWZpY2F0ZTElMCMGCSqGSIb3DQEJARYWaW5mb0B0cmli
ZXBheW1lbnRzLmNvbTEZMBcGA1UEYQwQR0ItVFNULTAwMDAwMDAwMDCCASIwDQYJ
KoZIhvcNAQEBBQADggEPADCCAQoCggEBANxZeuMSN1RyuMj/xNfwPzfW3ffepWQ4
PYSE6kdja75EALosifw6n5RhDte9De57xxXnQAzyJcCGC/4GCpMfzecN/hcmSxHZ
he8zbITqRmyLPXbcaEswDnGYRxIGNqGG2RWKZ6I0wSGK89t1Fw1Kz8ob8Lzh6k0U
QNfujYOItTaVM4JCgKp5yjTb0HWcqp7X2Jb0eamMWfY5cxKolbJYSIlclt4loAhp
EdCiqVJi5hc05+GrsSjchjNQzUpwot/GZFfm2faBPSR5sfxV0B+pXLehmzXdF7nA
6Q2hAqXb8jjpbIXgDzcSRdaP7kNBLzXzNuUUUNf2LL4rFkTn5k2XgrcCAwEAAaOB
yzCByDCBxQYIKwYBBQUHAQMEgbgwgbUwCAYGBACORgEBMAwGBgQAjkYBBTACMAAw
dAYGBACBmCcCMGowTDARBgcEAIGYJwEDDAZQU1BfQUkwEQYHBACBmCcBAQwGUFNQ
X0FTMBEGBwQAgZgnAQIMBlBTUF9QSTARBgcEAIGYJwEEDAZQU1BfSUMMEVRyaWJl
IFBheW1lbnRzIENBDAdHQi1URVNUMCUGBgQAjkYBBjAbBgcEAI5GAQYBBgcEAI5G
AQYCBgcEAI5GAQYDMA0GCSqGSIb3DQEBCwUAA4ICAQAl7lnznKu32NhEbsChJABM
q66m1gJ38vYPdb4bt3cbXml9EGUHuj8ObPcz+drrPE7DWc0VRVNWsddx8iNUB/Wv
dt88ViML58mxZhvbD1NWJ9L4s51ZdRxcqBNJwpTxV1Gb1KcXVtbWQRoDeUbT5m/K
/IJqfgpqCZsd7Rxs5g1cDdXT0wHT9bUj5BsWJD1ZDhMgQDpiUhJkAx29hWu1BhAA
vf3BvHdsnBQ/85iLYB3iZIbkZINhoSnwTFkXD957JrKGn2iu807mqY8kkIP+3cWk
NkZueCpAgoRQTtSUlETMhjJvUvdVRAQDjPuIHL8Ji2KIYrTl4+T2kZb8kxkccarz
wGy8mn7AgJrSl8Yzh4ojDLlUiR96zkTMd/RPACjmohCwlKrYM5e65fxu8j9CGbMH
jFV8MqqiaXL0f2gMZPHNSEZ/3c/znOCQ4igvT9IaV7tpCIH51/jn573lQDobIf7P
dTbCwj+PTCAeDSkKUM8dKKsvZnkcxy5sxwBy1DYLNU7ggDmNzIR1LzAMmf+hlZ86
l3W/tUEr+ij3gw3zw66Op2X4K0pkqTvhOqVV2bbeAd/WA1uJbc8GxLc8VjKEAkBS
0vi7IHLPdY5VPvZ4XaQAG5YYTLKyBb9gMiAKzEzLAT/wThb6HASge3OBvfpsUzEV
DKuPzlaSsu8JK9daNkZG4A==

This private key can be used to sign a request:

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA3Fl64xI3VHK4yP/E1/A/N9bd996lZDg9hITqR2NrvkQAuiyJ
/DqflGEO170N7nvHFedADPIlwIYL/gYKkx/N5w3+FyZLEdmF7zNshOpGbIs9dtxo
SzAOcZhHEgY2oYbZFYpnojTBIYrz23UXDUrPyhvwvOHqTRRA1+6Ng4i1NpUzgkKA
qnnKNNvQdZyqntfYlvR5qYxZ9jlzEqiVslhIiVyW3iWgCGkR0KKpUmLmFzTn4aux
KNyGM1DNSnCi38ZkV+bZ9oE9JHmx/FXQH6lct6GbNd0XucDpDaECpdvyOOlsheAP
NxJF1o/uQ0EvNfM25RRQ1/YsvisWROfmTZeCtwIDAQABAoIBAD+mbVP4aBkxxmTx
VPgXgvtrStUV8GqhwEtuZYpXksD0Pc2JnhZJDN28p5/0EXkpMhoGob7bl8IkNoSb
VCSplD3BEfu36Qlv7ztofFlsnwkts4SJKGtHp3Ryy1zOhKtmG4EYaNU3Le61h7mF
+jGxwZIdPg4hqB+50P1PAHvVWps4Nq3wYkk7m6Ogj5mpH6/Lx6d87GXp7wQEr1GF
OLEs0h9oeb/40wu77ggSOsC7MfRir+mYfKVlE0zQd8e5R7GR87hjpyjbgxI5/soP
5QbiQCPlzYgwTq3rgjMZavvydQShKsvwRjIijAVEPhEfXY5o1GDK77TEsutsJpHX
rgwV59ECgYEA+qec80+fOfgJ0rdeBnytGdkrK5zP2/Br3dYsUBn4GbEgsDdWFnX1
r9OlwG+TJo5NUwEIUU8NfMJ6gLRujGy4AbOwxkddOSOi0nstk3qpqOoD8w7bHx68
jJDV32+n2gxD2+AJoGoG6EIx60qGC2V93mRdqlD6GWB8XpFDc4q3HokCgYEA4Qxs
WQNqtGF9y5IRyAYnq1iWZKKQef5Xr8rRrc9dsNYP763EZPVUZ7xDqdDy2BWWSsFX
TjEPwtb6V8e+gjbwSw2W3Zl+wSnkxjdTtiLkbTLcnPgZa+Jf0HbZQRQiNEmAetIR
2aOWRQLbwWvz8KIxEm7KoWSCdLONIIfPxtzXRz8CgYEAz6eIuXIfQZEh4jYTaWBk
r+NghnMVKOrXEiNa9sls5yv9Hr/ZTCZRcmbvDKvixrBhkwBp+aJ6U/9yKapRY3i2
QIKzUrDQpIPHYoS1z1ZxtASbXQPTuMZoAjQDW2ZPMq+ykDfdAc6VBlnArWNCBbMB
Qfr4Nh978wYiQt4peVFUP7ECgYB4KpwIA60MWCpFct+PwMmZ0pmrbqpamZbUxSWk
+175t7OWtWBy0BSbt4khufKRsyUnEYm+tK/Hx+awzHVLLm6shLsT5IwsNGR1+sD2
Njdmn4vxPQDF/IBQ3cUv3MJOzRiPfHAPmCv6+YXCCBSfXtt5DjOgbfzCt8UZo6ss
cmt5HQKBgCLk8nklWhsjD4oMlt2BeVUvP0WMPbWZ92pNjCzGPlTfg8/JwYlbW1pM
a4eDAwfjfMSlPqaz7dR+k6NsSAy9ViENqPBUgYjbWQEdHqyQACG4ZoH/6TAuNm/T
d8BX1pujop98PPcAKqlvDHUVJQ1ALBmihsS+o9VmUMvB0qRKupl1
-----END RSA PRIVATE KEY-----

Error code

Code Description
4000 Unknown error
4001 Wrong request content
4002 Internal server error
4003 Request body is not valid JSON.
4004 Exhausted API access limit
4005 Bank not found
4200 Wrong credentials
4201 Authentication required
4202 This API action does not exist.
4203 Request to ASPSP failed
4204 Header "X-Request-Id" is not valid UUID
4205 Digest is not valid.
4300 Parameter "bic" does not exist.
4301 Parameter "bic" is not valid.
4302 Parameter "scope" does not exist.
4303 Parameter "scope" is not correct.
4400 Parameter "client_id" does not exist.
4401 Parameter "grant_type" does not exist.
4402 Parameter "grant_type" is not correct.
4403 Parameter "code" does not exist.
4404 Only one of client_secret/code_verifier must be present.
4405 Parameter "code" is not correct.
4406 Parameter "refresh_token" does not exist.
4407 Parameter "refresh_token" is not correct.
4500 Parameter "iban" does not exist.
4501 Parameter "iban" is not correct.
4602 Payment initiation failed.

Payment status

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

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

Withdrawal purpose

Code Description
MWI Mobile wallet cash in
MWO Mobile wallet cash out
MWP Mobile wallet payments
SVI Stored value card cash-in
SVO Stored value card cash-out
SVP Stored value card payments
FSA Equity other than investment fund shares in the related companies abroad
ACM Agency Commission
AFA Receipts or payments from personal residents bank account or deposits abroad
ALW Allowances
ATS Air transport
CCP Corporate Card Payment
CEA Equity for the establishment of new company from residents abroad equity of merger or acquisition of companies abroad from residents and participation to capital increase of related company abroad.
CEL Equity for the establishment of new company in the UAE from residents equity of merger or acquisition of companies in the UAE from n-residents participation to capital increase of related companies.
CHC Charitable Contributions
COM Commission
COP Compensation
CRP Credit Card Payments
DCP Pre-Paid Reloadable and Personalized Debit Card Payments
DIV Dividend Payouts
DOE Dividends on equity not intra group
EDU Educational Support
EMI Equated Monthly Instalments
EOS End of Service
FAM Family Support
FIS Financial services
FSL Equity other than investment fund shares in related companies in the UAE.
GDS Goods Bought or Sold
GMS Processing repair and maintenance services on goods
GOS Government goods and services embassies etc.
GRI Government related income taxes tariffs capital transfers etc.
IFS Information services
IGD Intra group dividends
IGT Inter group transfer
INS Insurance services
IPC Charges for the use of intellectual property royalties.
ITS Computer services
LAS Leave salary
MCR Monetary Claim Reimbursements Medical Insurance or Auto Insurance etc.
OAT Own account transfer
OTS Other modes of transport
OVT Overtime
PEN Pension
PMS Professional and management consulting services
POS POS Merchant Settlement
PRS Personal cultural audio visual and recreational services
RDS Research and development services
RNT Rent Payments
SAL Salary
SCO Construction
STR Travel
STS Sea transport
SAA Salary Advance
TCS Telecommunication services
TKT Tickets
TOF Transfer of funds between persons Normal and Juridical
UTL Utility Bill Payments
OTH Other

Security

Authentication

PSU authentication is implemented via OAuth2 standard.

Based on ASPSP compliance with PSD2 and TPP authentication, each request to certain ASPSPs needs to provide HTTP Signature in headers signed with valid EIDAS (Electronic IDentification, Authentication and Trust Services) certificate used for eSeal.

These parameters should be included in the header of each request to identify licensed TPP provider.

Parameter M Type Length Description
X-Client-Id M AN 256 TPP application credentials: ID
X-Request-Id M AN 36 Unique request ID generated by the TPP - must be valid UUID
Signature C AN - Example: keyId="SN=3595A71FCB74E837959C3F0CF5F73A03B31F1952,CA=TribePayments CA",algorithm="rsa-sha256",headers="digest x-request-id x-client-id",signature="fNQmDCpFT5K8qAx0bNvNQsRfCm9mGKN/Srv7pufS07s8VuEGGk7HTVGVfwkYFrhpnXxtWimu77/3o+U+v61ZYsLdfOyKpv3v8u3jwee3warI6u+FyZbBvMFDnzWND68lecWB5OTdh6GlNQp8fQKp/ef/mJOVGhZ1wMVVTMH9kbH6/hVV6OoYpMs0kpIpfglnWXDJSiu8glTAGi7iC5n9eWCDunoH0a2QT2vr/gI6acEvPIin2Cqm8rIGCYk43G8K1fhdVaMDvhkyG76ld/IM7wVWzBkxiwrDYf1h3nDpzxPhJKHUv4d/BMcUd2JuVW+y5yYMd8RUnf6Ti5mmSEC90w==".
Tpp-Signature-Certificate C AN - Necessary if TPP certificate was not provided by other means. An example of a QSEAL Certificate.
Authorization C AN 256 PSU access token. Format: "Bearer \". The parameter is not needed when not accessing actual account data of a PSU.

Example

Calculating digest

$calculatedDigest = hash('sha256', '{"message":"some request content"}', true);
$encodedDigest = base64_encode($calculatedDigest);

$digest = 'SHA-256='.$encodedDigest;

Calculating signature

$privateKey = '-----BEGIN RSA PRIVATE KEY-...';
$signingString = "Digest: SHA-256=LsUn8L4rScYKhYKf8eNr5QIbiB+1n9wFioBJ0C3XSU8=\nx-request-id: 30af7a2f-b18d-4bc3-a9b7-c24395937dea\nx-client-id: 13156d583a08944d51580837e165871d";

openssl_sign($signingString, $sign, $privateKey, 'rsa-sha256');
$encodedSign = base64_encode($sign);

$signature = 'keyId="SN=3595A71FCB74E837959C3F0CF5F73A03B31F1952,CA=TribePayments CA",algorithm="rsa-sha256",headers="digest x-request-id x-client-id",signature="'.$encodedSign.'"';

Direct security

Authentication

PSU authentication is implemented via callback URL where user after the call should be redirected for SCA (2-factor authentication).

Based on ASPSP compliance with PSD2 and TPP authentication, each request to certain ASPSPs needs to provide HTTP Signature in headers signed with valid EIDAS (Electronic IDentification, Authentication and Trust Services) certificate used for eSeal.

These parameters should be included in the header of each request to identify licensed TPP provider.

Parameter M Type Length Description
X-Client-Id M AN 256 TPP application credentials: ID
X-Request-Id M AN 36 Unique request ID generated by the TPP - must be valid UUID
Signature C AN - Example: keyId="SN=3595A71FCB74E837959C3F0CF5F73A03B31F1952,CA=TribePayments CA",algorithm="rsa-sha256",headers="digest x-request-id x-client-id",signature="fNQmDCpFT5K8qAx0bNvNQsRfCm9mGKN/Srv7pufS07s8VuEGGk7HTVGVfwkYFrhpnXxtWimu77/3o+U+v61ZYsLdfOyKpv3v8u3jwee3warI6u+FyZbBvMFDnzWND68lecWB5OTdh6GlNQp8fQKp/ef/mJOVGhZ1wMVVTMH9kbH6/hVV6OoYpMs0kpIpfglnWXDJSiu8glTAGi7iC5n9eWCDunoH0a2QT2vr/gI6acEvPIin2Cqm8rIGCYk43G8K1fhdVaMDvhkyG76ld/IM7wVWzBkxiwrDYf1h3nDpzxPhJKHUv4d/BMcUd2JuVW+y5yYMd8RUnf6Ti5mmSEC90w==".
Tpp-Signature-Certificate C AN - Necessary if TPP certificate was not provided by other means. An example of a QSEAL Certificate.

Notation

Abbreviation

Abbreviation Description
TOB Tribe Open Banking
ASPSP Account Servicing Payment Service Provider
BANK Account Servicing Payment Service Provider (ASPSP)
AISP Account Information Service Provider
PISP Payment Initiation Service Provider
TPP Third-Party Provider (TPP) is a provider of an application that the PSU uses and is not offered by the BANK. TPP is the client/consumer of the API and acts on behalf of the PSU.
SCA The process of using a strong (2-factor) identification method to identify the customer.
Consent Consent is the agreement given by the customer to the TPP to retrieve the user'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
BIC BANK Identifier Code

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
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. It uses Oauth2 standard with authorization_code flow and optionally PKCE security extension.

As long as consents are valid this procedure does not need to be repeated (optionally need to refresh access tokens), except for the authorization in the payments flow when TPP client does not use persistent consent options in it's provided settings.

The workflow of the authorization:

Preconditions: TPP should register client application in the TOB.

  1. The user logs into TPP and selects the BANK he wants to connect with.

  2. Does the TPP need to receive all possible scopes?

    If the TPP needs:

    1. It can request all possible scopes in the selected BANK.

    2. If the scopes list was requested by the TPP the TOB sends the response with the list of all possible scopes regarding the BANK selection.

  3. TPP sends the authorization request with the selected BANK BIC code to the TOB.

  4. TOB utilizes the BIC code to identify which BANK was selected by the user and provides the relevant link to it.

  5. Once the TPP receives the link, TPP redirects the user to the received URL.

  6. The user should go through the authorization in the selected BANK.

  7. Was the authorization successful?

    If "no":

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

    2. TPP displays cancellation information for PSU.

  8. Have the PSU approved scopes?

    If "no":

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

    2. TPP displays cancellation information for PSU.

    If "yes":

    1. The BANK redirects the user back to the TPP site with authorization data in URL query.
⚠ Warning!
All the requested scopes must be approved: not more and not less. Otherwise, the authorization procedure will not be successful.
  1. TPP sends request with authorization data from URL query.

  2. TOB responds with authorization tokens and other information.

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 authorization tokens.

The workflow of the get info:
  1. TPP sends the request with the required object to TOB.

  2. TOB checks if the scopes are approved.

    If "no":

    1. The TOB sends the error message to TPP that authorization did not succeed.

    If "yes":

    1. TPP receives data it requested.

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 until point 8 and token is expired after it's used.

  • Reusable consent which does not expire after single use and can be used for payment repeatedly.

The workflow for payment:

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

  1. The user logs into TPP and selects the BANK he wants to connect with.

  2. Does the TPP need to receive all possible scopes list?

    If the TPP needs:

    1. It can request all possible consents list in the selected BANK.

    2. If the scopes list was requested by the TPP the TOB sends the response with the list of all possible scopes regarding the BANK selection.

  3. TPP sends the authorization request with the selected BANK BIC code to the TOB.

  4. TOB utilizes the BIC code to identify which BANK was selected by the user and provides the relevant link to it.

  5. Once the TPP receives the link, TPP redirects the user to the received URL.

  6. The user should go through the authorization in the selected BANK.

  7. Was the authorization successful?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP with cancel information.

    2. TPP displays cancellation information for PSU.

  8. Have the PSU approved scopes?

    If "no":

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

    2. TPP displays cancellation information for PSU.

    If "yes":

    1. 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. TPP sends request with authorization data from URL query.

  2. TOB responds with authorization tokens and other information.

  3. The TPP sends payment request to TOB.

  4. Checks are performed if payment can be successfully executed (eg. account amounts).

    If "not":

    1. Flow is canceled, error information is returned for request.
  5. TPP receives confirmation information with request_url that needs to be confirmed.

  6. TPP redirects the user to the received URL address.

  7. User confirms payment with the selected tool (e.g. OTP PIN2). Does the user confirm the payment?

    If "no":

    1. The payment will be cancelled, and the user will be redirected to callback URL and TPP receives cancellation information inside redirect callback_url URL query (status, message query parameters).

    If "yes":

    1. Payment proceeds and user is redirected back to TPP callback_url.
  8. Was there any reason to decline the payment?

    If "yes":

    1. Flow is canceled, user is redirected back to TPP and receives cancellation information inside redirect URL callback_url query (status, message query parameters).
  9. As soon as the payment is done the BANK sends payment information in redirect URL.

  10. If TPP detects payment status change it sends the webhook with new payment status to TPP.

  11. The TPP displays the payments status for the user.

Direct payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

The workflow for direct payment:

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

  1. The user logs into TPP and selects the BANK he wants to request payment with.

  2. TPP uses bank_identifier parameter in URL to select BANK and sends payment request to TOB.

  3. Checks are performed if payment can be successfully executed (eg. account amounts).

    If "not":

    1. Flow is canceled, user is redirected back to TPP and receives cancellation information.
  4. TPP receives confirmation information with request_url that needs to be confirmed.

  5. TPP redirects the user to the received URL address.

  6. User confirms payment with the selected tool (e.g. OTP PIN2). Does the user confirm the payment?

    If "no":

    1. The payment will be cancelled and TPP receives cancellation information inside redirect URL query (status, message, identifier, payment_id query parameters).

    If "yes":

    1. Payment proceeds and user is redirected back to TPP (status, identifier, payment_id query parameters).
  7. Was there any reason to decline the payment?

    If "yes":

    1. The payment will be cancelled and TPP receives cancellation information inside redirect URL query (status, message, identifier, payment_id query parameters).