Introduction

This guide is designed to help you understand the Tribe Open Banking workflow by testing out our API.

The user will be able to test the Open Banking solution by using our Wallet integration. The Wallet is designed as an example use case for BANKS. It shows how the integration can work, however, the BANK is able to create their own workflow.

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 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.
BIC BANK Identifier Code.

Getting started

Create an account / Sign In

In order to start testing and administrating your Tribe Open Banking account, you first need to sign in to the application:

  1. Go to https://openbank-sandbox.tribepayments.com/login in the browser, which will navigate you to the "Sign In" page seen below.

loginscreen

The "Sign In" screen

  1. Do you have an account already?

    If "no":

    1. Click the "Don't have account? Register" link under the "Sign in" button.

    2. The system navigates you to the register screen.

scr_create_user

Register screen

  1. Fill the fields:
Name What it means
Email Enter your email. Next time it will serve as the login username.
Password Enter your password.
Agree on terms When you have read through the terms, please check the box.
  1. Click the "Register" button:

    1. The system navigates you back to the "Sign In" screen.
  2. Enter your credentials:

Name What it means
Username Your email which was filled in the registration form is your username.
Password Enter your password which was created during the registration.
  1. Click the "Sign In" button.

  2. Were there any errors?

    If "yes":

    1. The system displays error messages. You need to amend and try to log in again.

    If "no":

    1. The system logs you in and navigates you to the Open Banking dashboard.

Create the client

  1. Go to the "Clients" list.

  2. Click on the BTN_create button to open the "Create client" screen.

create_client_scr

  1. Fill the required fields:
Name Type What it means
API ID Read-only The API ID credential will be generated automatically by the system once you save the form.
Active Checkbox By default, the checkbox is checked. You can uncheck it if you are creating an inactive client.
Title Text field Client title. Max length - 128 characters.
Callback URL Text field Default system provided value is for testing only, and will use system web interface to serve as an API client. Actual TPP client application callback URL should be used in production.

* Fields with the asterisk on the right-hand side of the label are required

  1. Click the "Create" button to save the form and create a new client record.

  2. Were there any errors in the form?

    If "yes":

    1. The system shows validation errors and asks you to correct them. You need to amend and repeat the 4th step.

    If "no":

    1. The system creates a record with the entered data and shows the message about the successfully created client.

Interact with the client

The client in the Tribe Open Banking system is the TPP. If a TPP wants to use the TOB they need to create a client.

The TPP can get their API ID from the client form. Without it, the client will not be authenticated in the TOB and unable to send requests.

Clients list can be accessed from the Left-side menu > Clients. In the "Clients" list you can:

  1. Filter the list.

  2. Navigate through the pages of the list.

  3. Create a new client.

  4. Review an already created client.

Review the client

  1. Go to the "Clients" list.

  2. Click the BTN_view button on the right-hand side of the selected record.

  3. The system opens the "View Client" screen. All the fields in the form are read-only.

view_client-scr

  1. You can click on the BTN_back button to leave the current screen and go back to the "Clients" list.

API testing

Tribe Open Banking API calls can be tested directly from the Tribe Open Banking GUI.

Authorization

The Oauth2 authorization code grant type flow can be tested in two different ways.

  1. Log into the TOB - the system will place you in the TOB Dashboard.

  2. Use the left side menu to navigate to the "Authorize" screen.

    left_side_menu_authorization

  3. Click Authorization > Authorize.

scr_authorization

  1. Fill all required fields:
Name Type What it means
Client * Single-select drop-down Select a (TPP) client.
Bank * Single-select drop-down Select a BANK.
Scopes * Multi-select list Select the scopes that need to be approved.

* Fields with the asterisk on the right-hand side of the label are required.

  1. Click the "Get Payload" button to start the procedure.
⚠ Warning!
The following description shows how you will go through the Wallet flow. If you select a different BANK you will go through the different procedure.
  1. The system navigates you to the second "Authorize screen" with read-only fields. In this screen, you will see the HTTP request that will be executed from the TPP to TOB.

    scr_auth_req

  2. If you want to execute the request, click the "Make request" button.

  3. The system will show the HTTP response to the executed request.

scr_authresponse

  1. If the request succeeds, it will return a JSON containing authorization redirect URL to ASPSP. You can follow the authorization redirect URL in response by clicking "Follow Redirect" button. The system will then navigate you to the ASPSP website.
  • In the case of using the Wallet flow, after clicking the "Follow Redirect" button, the system will navigate you to the Wallet environment login screen with the consent information.

Wallet_login_consents

Note: You can not reselect consents. All listed consents have to be signed.

  1. Enter your credentials and click "Log In".

  2. Once the system navigates you to the "Account selection" screen select the accounts that you want to grant access to and click "Confirm".

Wallet_acc_select

  1. The Wallet navigates you to the "Data confirmation" screen. Here you can check selected accounts, and if everything is correct, proceed by entering Key code and click "Confirm".

    Wallet_keycode

  2. The Wallet will navigate you to the Success screen, after which it redirects to client callback URL with "authorization_code" which can be exchanged for access token.

Wallet_success

  1. The TOB will open the callback URL, in this case - Authorization > Token screen filled with authorization code and state from HTTP redirect.

  2. Click the "Get Payload" button and the TOB will show the request which will be executed.

scr_auth_token

  1. Click the "Make request" button to make a request.

scr_authorization_token

  1. TOB will display you response information.

scr_token_response

Authorization flow can also be checked from a different location - API specs > Authorization. Here, you can also find all the specifications for the API and try to initiate each call separately.

  • Get redirect URL (POST/tpp/authorize selection)

  • Receive authorization or refresh tokens (POST/tpp/token selection)

  • Get all possible scopes that can be provided by ASPSP (GET/tpp/scope?bic={bic} selection)

  • Get the list of possible BANKS that can be accessed through TOB (GET/tpp/banks?page={page}&limit={limit} selection)

scr_Authorize_API

  1. Go to API specs > Authorization.

Left_side_menu

  1. TOB opens the Authorize OpenAPI specification screen.

scr_auth

  1. Select a server to which you need to authorize.

  2. Click the "Authorize" button to open the "Available authorizations" screen.

scr_headers_unauth

  1. Enter the Client ID (which can be found in the clients list), click the "Authorize" button (the system will lock the value entered in the Client ID field) and close the modal window.

scr_key_auth_locked

  1. If you want to change the client ID which is authorized already click the "Logout" button so the system will enable the field.

  2. Select the type of the message which should be tested from the list below and click on it to expand.

scr_Authorize_API

  1. Once you will click the "Try it out" button the system enables parameter fields for editing. Review the parameters and update if necessary. Additionally, enter the "Request body" information in JSON format if requested. For example:

    • If you are trying the POST/tpp/authorize API call, you have to enter ASPSP BIC and scopes information in JSON format.
    • If you are trying the POST/tpp/token API call, you will be asked to either enter the authorization code or refresh token (based on why you are sending the request).

scr_post_tpp_authorize

  1. Click the "Execute".

    1. If you want to clear all fields you need to click the "Clear" button.
  2. You will be able to see the response below.

scr_response_redirect_url

  1. You can see the example of the successful response below and compare it with the received one.

Get data

To test the "Get data" API calls, there are two options:

  • API Specs > Account can be used for getting account information (GET/tpp/accounts selection), specific account information (GET/tpp/account?iban {iban} selection), specific account balance information (GET/tpp/account_balance?iban={iban}).

  • API specs > Payments can be used for getting account payments information (GET/tpp/account_payments?iban{iban}&{record_count}&current_page={current_page} selection), specific payment information (GET/tpp/account_payment?payment_id={payment_id} selection).

The workflow:
  1. Go to the required location and select the API call which needs to be sent.

  2. Are you already authorized?

    If "no" click the "Authorize" button to open the "Available authorizations" modal window.

scr_headers

  1. Fill in the access token information in the "tokenAuth(http, Bearer)" field and click the "Authorize" button and the system will lock the value.

    1. Fill in the client API ID information in the "clientID (apiKey)" field and click the "Authorize" button and the system will lock the value.

    2. If for any reason you need to change the value in any of these two fields click the "Logout" button near the selected field and the system will unlock the value in the field.

  2. Select which message should be run and click on it.

  3. The system expands required message.

  4. Click the "Try it out" button to start the flow.

  5. The system opens the parameters and the "Execute" button.

  6. Update parameters if needed, enter IBAN (if needed) which information should be received and click the "Execute" button.

  7. The system generates a curl command and shows the response.

  8. You can find the example of the successful response under your actual response so you can compare them.

  9. Do you want to proceed again?

    If "No":

    1. Click the "Clear" button.

    2. the system cancels the flow and removes the generated information from the screen.

    If "Yes":

    1. Click the "Execute" button.

    2. The system will send the request and display the response again.

Payment

Payment initiation message can be tried from API specs > Payments.

  1. Go to API specs > Payments.

  2. Select the "POST/tpp/payment_initiation" message and click on it.

  3. The system will expand the message information.

scr_POST_tpp_payment_init

  1. Are you already authorized?

    If "no" click the "Authorize" button to open the "Available authorizations" modal window.

scr_headers

  1. Fill token information in the "tokenAuth(http, Bearer)" field and click the "Authorize" button and the system will lock the value.

    1. Fill token information in the "clientID (apiKey)" field and click the "Authorize" button and the system will lock the value.

    2. If for any reason you need to change the value in any of these two fields click the "Logout" button near the selected field and the system will unlock the value in the field.

⚠ Warning!
The authorization should be done each time you are initiating the payment. The same token can not be used for two different payments.
  1. Click the "Try it out" button to start the flow.

  2. The system opens the parameters and the "Execute" button.

  3. Update parameters if needed, enter request body information with the information about the payment which needs to be executed and click the "Execute" button.

  4. The system generates a response.

  5. You can find the example of the successful response under your actual response so you can compare them.

  6. Do you want to proceed again?

    If "No":

    1. Click the "Clear" button.

    2. the system cancels the flow and removes the generated information from the screen.

    If "Yes":

    1. Click the "Execute" button.

    2. The system will send the request and display the response again.