Introduction

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.

Overview

Payments powered by Open Banking also offer near real-time transfers, guaranteeing payments or refunds are received quickly, as well as products being shipped. Meanwhile, chargebacks which merchants traditionally pay for because of card fraud or rejected card payments, simply disappear.

Tribe Open Banking has developed REST APIs allowing third party providers (TPPs) connectivity into the Tribe partner base. We call this: Inbound Processing Request.

This is our core TPP product. Tribe has created a set of APIs that its partners will continue to use as their Open Banking requirements grow. This will communicate directly with our Isaac platform to give you the relevant data and payment information. Tribe has partnered with Open Banking Europe to enable TPP verification so our partners can ensure that we are only working with registered TPPs.

This documentation is created to cover Tribe Open Banking (TOB) communication with the BANK. You can find communication descriptions between the TPP and the BANK during:

  • Authorization procedure.
  • Getting information about all possible scopes in the BANK.
  • Payment initiation procedure.
  • Get (accounts, account, account balance, account payments, payment) information from the BANK procedure.

In order to see these procedures flow charts and sequence diagrams, please see the Workflow.

🛈 The terms and their descriptions can be found in the Notation section, additionally, a QSEAL certificate example can be found in the Certificate example section.

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 numerous 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. Mandatory if any error occurred.

Webhooks

Webhooks are HTTP callbacks triggered by an event in a web application. Open Banking TPP API uses webhooks to asynchronously let your application know when events happen - like getting the latest payment status from the TOB.

Workflow for webhooks:

tpp webhook diagram

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

Actions

Account

Balance

"Get account balance" message is initiated by the TPP and it is the part of the Get data flow. TPP requests selected account balance information from TOB which requests the information from the BANK. The account.balance consent (scope) should be signed to get the successful response.

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

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/account_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/account_balance?iban=GB999999999999999999

Response

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

Get

"Get account" message is initiated by the TPP and it is the part of the Get data flow. TPP requests the selected account information from TOB which requests the information from the BANK. The TOB responds to TPP with the requested account details. The account.details consent (scope) should be signed to receive a successful response.

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

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/account 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/account?iban=GB999999999999999999 

Response

Parameter M Type Length Description
account M LIST Under this parameter all requested accounts will be listed.
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 regarding ISO 4217.
additional_data M LIST Listed additional data.
{
  "id": 15922246314898,
  "name": "John Doe",
  "iban": "GB999999999999999999",
  "currency": "EUR",
  "additional_data": []
}

Get list

"Get accounts" message is initiated by the TPP. TPP requests client's accounts information from TOB which requests the information from the BANK. The "account.list" consent (scope) should be signed to receive a successful response.

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

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

Request

TOB sends the Headers to the required endpoint.

Response

Parameter M Type Length What it means
accounts M LIST Under this parameter all requested accounts will be listed.
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 AN 3 Currency abbreviation regarding ISO 4217.
additional_data M LIST Listed additional data.
{
  "accounts": [
    {
      "id": 15922246314898,
      "name": "John Doe",
      "iban": "GB999999999999999999",
      "currency": "EUR",
      "additional_data": []
    },
    {
      "id": 15922273037137,
      "name": "Jane Doe",
      "iban": "GB888888888888888888",
      "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. TPP requests selected account payment information from TOB which requests the information from the BANK. The "account.payment" consent(scope) should be signed to receive a successful response.

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

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

Request

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

Response

Parameter M Type Length Description
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.
description M AN 255 Information about the transfer.
additional_data M LIST
sender_data M LIST
iban M AN 34 The IBAN from 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 from which the transfer was made.
currency M AN 3 Sender account currency code.
receiver data M LIST
iban M 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,
    "description": "Transfer from IBAN (GB999999999999999999) to IBAN (GB888888888888888888)",
    "additional_data": [
      {
        "sender_data": {
          "iban": "GB999999999999999999",
          "account_name": "John Doe",
          "account_number": "4164513165",
          "sort_code": "222444",
          "bic": "TRB00XXX",
          "currency": "EUR"
        },
        "receiver_data": {
          "iban": "GB888888888888888888",
          "account_name": "Jane Doe",
          "account_number": "4165445",
          "sort_code": "111112",
          "bic": "TRB00XXX",
          "currency": "EUR"
        }
      }
    ]
  }
}

Get payments

"Get account payments" message is initiated by the TPP and it is the part of the Get data flow. TPP requests a selected account payments list with its information from TOB which requests the information from the BANK. The "account.payment" consent (Scope) should be signed to receive the successful response.

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

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

Request

Parameter M Type Length Description
iban M AN 34 Account IBAN number.
record_count O N 3 Payment count per page. Max is 100. Default is 10.
current_page O N 3 Default value is 1.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/account_payments?iban=GB999999999999999999&record_count=15&current_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.
currency M A 3 ISO 4217 format.
description M AN 255 Information about the transfer.
additional_data M LIST
sender_data M LIST
iban M AN 34 The IBAN from 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 from which the transfer was made.
currency M AN 3 Sender account currency code. ISO 4217 format.
receiver_data M LIST
iban M AN 34 The IBAN to which the transfer was made.
account_name M AN 6 The name of the account.
account_number M AN 12 The account number.
sort_code M AN 3 The sort code.
bic M AN BANK identifier code to which the transfer was made.
currency M AN 3 Receiver account currency code. ISO 4217 format.
paginator M LIST Paginator details.
limit M N 3 Current limitation status. The max value is 100.
current_page M N 3 Defines the page should be provided.
{
  "payments": [
    {
      "id": "15910999261806",
      "reference": "BB200400490",
      "date_created": "2015-12-05",
      "amount": 5500.00,
      "currency": "EUR",
      "description": "Transfer from IBAN (GB999999999999999999) to IBAN (GB888888888888888888)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB9999999999999999",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          },
          "receiver_data": {
            "iban": "GB888888888888888888",
            "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,
      "currency": "EUR",
      "description": "Transfer from IBAN (GB999999999999999999) to IBAN (GB888888888888888888)",
      "additional_data": [
        {
          "sender_data": {
            "iban": "GB888888888888888888",
            "account_name": "Jane Doe",
            "account_number": "1321654",
            "sort_code": "333444",
            "bic": "CCCGB22XXX",
            "currency": "GBP"
          },
          "receiver_data": {
            "iban": "GB999999999999999999",
            "account_name": "John Doe",
            "account_number": "4164513165",
            "sort_code": "222444",
            "bic": "TRB00XXX",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "paginator": {
    "limit": 15,
    "current_page": 2
  }
}

Authorization

If the TPP needs to, it can request the list of available scopes that need to be signed in order to get the access to the selected BANK. The message is optional part of the Authorization flow.

Endpoint Method
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/scope GET
Parameter M Type Length Description
bic M AN 11 The selected BANK identification code to which PSU wants to authorize code.
https://tpp-api.openbank-sandbox.tribepayments.com/tpp/scope?bic=AAAAAA00000
Parameter M Type Length Description
scopes M LIST Possible scopes
{
  "scopes": "account.list account.details account.balance account.payment"
}

Initial

The message is necessary to start the Authorization (OAuth 2.0) process and retrieve the ASPSP authorization URL to which the PSU should be navigated to make its authorization.

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

Request

Parameter M Type Length Description
bic M AN 11 The selected BANK identifier code to which PSU wants to authorize code.
scope M AN 256 OAuth2.0 standard defined scope.
state O AN 256 OAuth2.0 standard defined state.
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.balance 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://example.com/authorize/d5v3e8q6v"
}

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.

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".
redirect_url C AN - OAuth Redirect url. 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 is used.
{
    "grant_type": "refresh_token"
}

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. The parameter will be provided when the grant_type is = "authorization_code".
refresh_token_expires_in C N 11 Expiration of refresh_token in seconds. Provided when the grant_type is = "authorization_code".
scopes C AN 255 The list of allowed scopes. Will be provided when grant_type = authorization_code.
{
    "token_type": "bearer",
    "access_token": "dca3af30ab481814c986f315407a6e2cd96d4a570f1fe5c5734d2be5c1a239dbeaf7819e72edeb082f385fc27aa93a5a53f331faa66d57588f5121b04f409e67ed743f4de9a5c880043f63c78157d5214680684863f22d13b645889aa89b3c8df12f45386c0c901987a092ad5ddc1aab17fd7cac9f55a5908f73847bcbd681",
    "expires_in": 1799,
}

Bank

Get list

The message is necessary for TPP to get the list of BANKS (with identifiers) that are integrated with the TOB.

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

Request

Parameter M Type Description
limit O AN
page O AN OAuth2.0 standard defined scope.
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"
    }
  ]
}

Payment

Initiate

"Payment initiate" message is initiated by the TPP and it is the part of the payment flow. TPP requests TOB to initiate the payment. After the authorization is done, the TOB requests the BANK to initiate the payment. The "payment.init" consent (scope) should be signed to receive a successful response.

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

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

Request

Parameter M Type Length Description
sender_iban M AN 34
amount M N 10
receiver_name M A 40
currency M A 3 ISO 4217. The BANK can check if it matches the sender_iban account's currency.
reference M AN 18 Payment identification, which must be generated in the TPP. Unique to each payment.
receiver_iban C AN 34 If "receiver_ban" 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 TPP.
{
  "sender_iban": "GB21IBA00000000000000",
  "amount": 1500.00,
  "receiver_name": "Company Ltd",
  "currency": "EUR",
  "reference": "BB46DS542136",
  "callback_url": "https://example.com/"
}

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

Webhooks

Payment status

The "payment status" message is necessary for the TPP to get the information when the BANK proceeds with the payment. It is the part of the payment flow. As soon as payment is finished the system sends the webhook that the payment is done and the TPP should respond that the webhook was received successfully.

Request

Parameter M Type Description
status M AN 10 Returns the status of the request: whether it was successful or if any errors have occurred.
payment_id M N 11 Unique payment identifier.
payment_status O AN 20 Possible values: 1 - pending 2 - sent 3 - received 4 - accepted 5 - settled 6 - rejected 7 - returned 8 - reversed 9 - canceled 10 - held. Will be empty if the status is "error".
{
  "status": "success",
  "payment_id": "454651545114",
}

Response

When you receive a webhook event, you must always return a 200 OK HTTP response in order for it to be successful.

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 you can use this QSEAL Certificate in the Tpp-Signature-Certificate header:

MIIF1DCCA7ygAwIBAgIUNZWnH8t06DeVnD8M9fc6A7MfGVIwDQYJKoZIhvcNAQEL
BQAwgbAxCzAJBgNVBAYTAlVLMQ8wDQYDVQQIDAZMb25kb24xDzANBgNVBAcMBkxv
bmRvbjEZMBcGA1UECgwQVHJpYmVQYXltZW50cyBDQTEZMBcGA1UECwwQT3BlbkJh
bmtpbmcgVGVhbTEiMCAGA1UEAwwZVHBwVGVzdCBRU0VBTCBDZXJ0aWZpY2F0ZTEl
MCMGCSqGSIb3DQEJARYWaW5mb0B0cmliZXBheW1lbnRzLmNvbTAeFw0yMDA4Mjgw
NzU4MTlaFw0yMTAzMDIwNzU4MTlaMIHIMQswCQYDVQQGEwJVSzEPMA0GA1UECAwG
TG9uZG9uMQ8wDQYDVQQHDAZMb25kb24xFjAUBgNVBAoMDVRyaWJlUGF5bWVudHMx
GTAXBgNVBAsMEE9wZW5iYW5raW5nIFRlYW0xIjAgBgNVBAMMGVRwcFRlc3QgUVNF
QUwgQ2VydGlmaWNhdGUxJTAjBgkqhkiG9w0BCQEWFmluZm9AdHJpYmVwYXltZW50
cy5jb20xGTAXBgNVBGEMEEdCLVRTVC0wMDAwMDAwMDAwggEiMA0GCSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQDcWXrjEjdUcrjI/8TX8D831t333qVkOD2EhOpHY2u+
RAC6LIn8Op+UYQ7XvQ3ue8cV50AM8iXAhgv+BgqTH83nDf4XJksR2YXvM2yE6kZs
iz123GhLMA5xmEcSBjahhtkVimeiNMEhivPbdRcNSs/KG/C84epNFEDX7o2DiLU2
lTOCQoCqeco029B1nKqe19iW9HmpjFn2OXMSqJWyWEiJXJbeJaAIaRHQoqlSYuYX
NOfhq7Eo3IYzUM1KcKLfxmRX5tn2gT0kebH8VdAfqVy3oZs13Re5wOkNoQKl2/I4
6WyF4A83EkXWj+5DQS818zblFFDX9iy+KxZE5+ZNl4K3AgMBAAGjgcswgcgwgcUG
CCsGAQUFBwEDBIG4MIG1MAgGBgQAjkYBATAMBgYEAI5GAQUwAjAAMHQGBgQAgZgn
AjBqMEwwEQYHBACBmCcBAwwGUFNQX0FJMBEGBwQAgZgnAQEMBlBTUF9BUzARBgcE
AIGYJwECDAZQU1BfUEkwEQYHBACBmCcBBAwGUFNQX0lDDBFUcmliZSBQYXltZW50
cyBDQQwHR0ItVEVTVDAlBgYEAI5GAQYwGwYHBACORgEGAQYHBACORgEGAgYHBACO
RgEGAzANBgkqhkiG9w0BAQsFAAOCAgEAp01fnm9PzE8XVDY/8rLimVuizfo8DBtJ
qzxxmZazbFa7VfD0jjME0FDxq+SzImziZ+nRwRWT+cE5FaDyTx3QkR01JqXtf8SS
1OEmEzo3NcGkXYWIy6gEbuPwryba5WQyVuF4tk3dHb4xGUj3kYFPPefEFRuJxCY0
iro86s8MlGdOlIee/HElF0XgNi4iMM9TRD0vWpgSC8hSGKoUkW18LDcqiFFlK2gQ
9gn6PdOWinhXeLruuMduYmzNLNgvBzgcKF6MMhfTiCpIpYhlUlhhFNTCiOnmAg+C
zf16/7TGfPKesJ8DE4gXfhxDOlntkOoswZOBaDqEJrkMgV4Yic4orzy9v7m3hXqB
/Ll445WVOl+iuAPL89lTaSBnmmW1DspiT7n8XsMC3WDkwTYK6i3nPh5IOE/kZcGH
CbqYqN/zugx7TYhRWVlwTb+jZH/Z6YOuFnDXFUqSgg0lH0K3419Ft5zRc7LtDdS9
mQDEDp+0OeT1TWHY4MtEOFdjLPElcXXTKDoGdOO/tXXXNFA7OR/4XAct7+Bm0sBz
oK/NQFnDJozCo23oeip6Cnp74OoHr8Dgkj2P3lzMqybqH1iZHLixw1Wt3Nvbko5y
QOjWzzUpRTEuI5dnzhv10g7oaKG2cgX39PE1imDRAtc6R4LiRzxewnHy2p+vB249
dqbcvpAgIjw=

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.
4200 Wrong credentials.
4201 Authentication required.
4202 This API action does not exist.
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.

Payment status

Status ID Description
1 Pending
2 Sent
3 Received
4 Accepted
5 Settled
6 Rejected
7 Returned
8 Reversed
9 Canceled
10 Held

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
payment.status PISP Get payment status

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

For TPP authentication a TLS 1.2 mutual authentication session should be established to TPP and BANK connection. PSU authentication is implemented via OAuth2 standard. In a live environment QWAC certificates must be used. These parameters should be included in the header of each request.

Parameter M Type Length Description
x-client-id M AN 256 TPP application credentials: ID.
x-client-secret M AN 256 TPP application credentials: password.
x-request-id M AN - Unique request ID generated by the TPP.
signature M 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 M AN - An example of a QSEAL Certificate.
authorization C AN 256 PSU access token. Format: "Bearer \". The parameter is not needed when sending the "Get Banks", "Authorize", "Consent scopes" and "Token" messages.

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.'"';

Notation

Abbreviation

Abbreviation Description
TOB Tribe Open Banking.
BANK Account Servicing Payment Service Provider (ASPSP) and Payment Initiation Service Provider (PISP).
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 The abbreviation for alphabetical inputs (A-Z a-z).
AN The abbreviation for alphanumeric inputs (0-9 A-Z a-z .!@).
LIST
N The abbreviation for 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. The user logs into TPP and selects the BANK he wants to log in.

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

    If the TPP needs:

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

    2. If the consents list was requested by the TPP the TOB sends the response with the list of all possible consents 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 links to it.

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

  6. The BANK sends the Initial authorization message to TOB.

  7. TOB responds with the TPP information, consents that need to be signed, and a URL address in which the user needs to be redirected if the consents will not be provided to TPP.

  8. The user should go through the authorization in the selected BANK flow. The flow depends on the selected BANK.

  9. Was the authorization successful?

    If "no":

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

    2. TOB sends the webhook with the cancelation information to TPP.

    3. TPP displays cancelation information for PSU.

  10. Does the PSU sign consents?

    If "no":

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

      1. TOB sends the webhook with the cancelation information to TPP.

      2. TPP displays cancelation information for PSU.

    If "yes":

    1. The BANK sends signed consents with the related accounts (IBANS / or, if IBANS are not provided - sort code together with account number) to the TOB. All signed consents except payment init, and payment status consents will be valid 90 days from the moment, they were signed. After 90 days they have to be signed again. Payment status consent and payment init consent are valid only for a single procedure. The next time the user initiates the payment consents must be signed again.

    2. The BANK directs the user back to the TPP site.

⚠ Warning!
All the requested consents must be signed: not more and not less. Otherwise, the authorization procedure will not be successful.
  1. TOB sends a response with the callback URL (back to TPP site) and generated token.

Get data

Activity

activity get info

Sequence

get accounts sequence

Get data flow is necessary for the TPP to achieve information from the BANK. The TPP can request PSU accounts list, account details, account balance, account payments, payment list. Access to information depends on which consents were signed on the BANK side/ which permissions were provided from the BANK for TPP, e.g. if the TPP does not have consent for the account details, account details will no be provided for the TPP. Consents are valid 90 days after they were signed, if the consents are no longer valid the access needs to be authorized again.

Get data can be initiated without user interaction. The TPP itself can request for the information.

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

  2. TOB checks if the consents are valid.

    If "no":

    1. The TOB sends the error message to TPP that consents are expired.

    If "yes":

    1. Sends the request to the BANK.
  3. BANK sends the response with the requested information to the TOB.

  4. TOB sends the response with the requested information to TPP.

Payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

The payment flow is necessary for the TPP consents to access the accounts and their information in the BANK, and for the PSU to initiate a payment from the BANK while he is interacting on the TTP side.

The payment flow has two steps: authorization in the BANK and the payment.

The authorization flow is similar to the authorization flow above, and the messages are identical.

There are two types of consents:

  • Accounts consents: "account payment" "account payments", "PSU accounts list", "account details", "account balance", "account payments" – are valid for 90 days after they have been signed.

  • Payment consents: "payment init" and "payment status". "payment init" consent is only valid for that single payment procedure and must be signed during the payment flow. That means that every time the payment is initiated "Payment init" payment consent must be signed.

For the initial payment all consents (account and payment) must be signed. For any subsequent payments (for the next 90 days), only the payment consents must be given.

The workflow:

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 log in.

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

    If the TPP needs:

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

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

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

  4. TOB regarding the BIC code defines which BANK was selected by the user and provides the link to it.

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

  6. The BANK sends the "Initial authorization" message to TOB.

  7. TOB responds with the TPP information, consents that need to be signed, and a URL address in which the user needs to be redirected if the consents will not be provided to TPP.

  8. The user should go through the authorization in the selected BANK flow. The flow depends on the selected BANK.

  9. Was the authorization successful?

    If "no":

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

    2. TOB sends the webhook with the cancelation information to TPP.

    3. TPP displays cancelation information for PSU.

  10. Does the PSU sign consents?

    If "no":

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

    2. TOB sends the webhook with the cancelation information to TPP.

    3. TPP displays cancelation information for PSU.

    If "yes":

    1. The BANK sends signed consents with the related accounts (IBANS / or, if IBANS are not provided - sort code together with account number) to the TOB. All signed consents, except for payment init consent, will be valid 90 days from the moment they were signed. After 90 days they have to be signed again. Payment init consent is valid only for a single procedure. The next time the user initiates the payment consents must be signed again.

    2. The BANK directs the user back to the TPP site.

⚠ Warning!
All the requested consents must be signed: not more and not less. Otherwise, the authorization procedure will not be successful.
  1. TOB sends a response with the callback URL (back to TPP site) and generated token.

  2. The TPP sends payment request to TOB.

  3. The TOB sends the payment request to the BANK.

  4. BANK checks if the PSU balance is enough?

    If "not":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancelation information to the TOB.
  5. TOB sends the webhook with the cancelation information to TPP.

  6. TPP displays cancelation information for the PSU.

  7. The BANK responds to the TOB with the confirmation URL to which the user needs to be redirected and payment ID.

  8. TOB sends received id and URL to TPP.

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

  10. The TOB requests the user to confirm payment with the selected tool (e.g. OTP PIN2). Does the user confirm the payment?

    If "no":

    1. The payment will be canceled and the user will be redirected to cancel URL.

    If "yes":

    1. The BANK redirects the user back to TPP and proceeds with the payment.
  11. Was there any reason to decline the payment?

    If "yes":

    1. The BANK cancels the payment and sends the webhook about cancelation to TOB.

    2. TOB sends the webhook with the cancelation information to TPP.

    3. TPP displays cancelation information for PSU.

  12. As soon as the payment is done the BANK sends the webhook with the payment status to TOB.

  13. TOB sends the webhook with the payment status to TPP.

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