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

Open Banking payments are authenticated directly between consumers and their own BANK.

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 REST APIs for BANKS enables its partners to use their extended permissions to initiate payment or data requests from third parties. This is designed to enable Tribe partners to deliver a richer experience within their own mobile application. For our partners that use our Digital Banking product, all of this information is displayed inside your own wallet.

This documentation covers Tribe Open Banking communication with the BANK. You can find communication descriptions between the BANK and the TOB (Tribe Open Banking) during:

  • Authorization procedure.
  • Saving consents.
  • Payment 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.

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:

bank action diagram

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

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

  • URL
  • Request format.
  • Response format.

URL

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

Request

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

Response

Response can be one of 2 types:

  • Success response.
  • Error response.
Success

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

Error

Error response is the same for all the actions, and the format is:

Parameter Requirement Type Length Description
error_code C N 4 Possible error codes Mandatory if any error occurred.
message C AN - Error message. Mandatory if any error occurred.

Webhooks

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

Workflow for webhooks:

bank webhook diagram

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

Actions

Authorization

Initial

The "Initial authorization" is the part of the Authorization flow between the BANK and TOB. The BANK sends POST/init authorization request to TOB immediately after the user authenticates himself in the BANK. The TOB responds with the TPP and necessary consents information and also adds the URL which needs to be used if the BANK does not want to provide the access.

Endpoint Method
https://bank-api.openbank-sandbox.tribepayments.com/bank/init_authorization POST

Request

Parameter M Type Length Description
request_url M AN - URL with all necessary information, e.g. "https://bank.example.com/redirect_uri=https://api.example.com/v1/callback&state=d73e24b1-099a-4278-b7b6-898ed24dc337&response_type=code&scopes=accounts%20payment.list%20consent%20account.lists%20funds.confirmations&client_id=112011111"
{  "request_url": "https://bank.example.com/obb/authorize/?hash=JFB45sdasdJHNFDD554" }

Response

Parameter M Type Length Description
tpp_name M AN - TOB sends TPP name which was parsed from the API-KEY in the header.
tpp_registration_number M AN - TOB provides TPP registration numbers.
scopes M LIST - Which consents needs to be signed. Possible values: account.list, account.balance account.payments, payment.list, payment.details, payment.init .
cancel_url M AN - The URL which was provided for the BANK in order the consents will not be signed.
{  "tpp_name": "TPP name",
   "tpp_registration_number": "UK-145441",  
   "scopes": [  
       "account.list", 
       "payment.list"  
    ],  
   "cancel_url": "https://tpp.example.com/authorize/cancel?hash=JFB45sdasdJHNFDD554"  }

"Save consent" message is initiated by the BANK. It is the part of the Authorization flow between the BANK and TOB. BANK sends the request with the consents (scopes) and accounts for which consents were signed, information. As soon as TOB gets a request from the BANK it responds with the callback URL and generated token.

Endpoint Method
https://bank-api.openbank-sandbox.tribepayments.com/bank/consent POST
Parameter M Type Length Description
scopes M AN - String type consents information that is allowed (e.g. account.list, payment.list).
request_url M AN - String type request_url as displayed previously.
ibans O LIST List of accounts (IBANs) which were selected during form submission step. Empty for payments.
iban O AN 34 Selected IBAN number.
{
  "scopes": [
    "payment.list",
    "account.list"
  ],
  "request_url": "https://bank.example.com/redirect_uri=https://api.example.com/v1/callback&state=d73e24b1-099a-4278-b7b6-898ed24dc337&response_type=code&scopes=accounts%20payment.list%20consent%20account.lists%20funds.confirmations&client_id=112011111",
  "ibans": [
    {
      "iban": "GB999999999999999999"
    },
    {
      "iban": "GB888888888888888888"
    },
    {
      "iban": "GB777777777777777777"
    }
  ]
}
Parameter M Type Description
callback_url M AN Callback URL to redirect the user back to the TPP.
access_token M AN A generated token which will be used in the following messages to BANK. The token is regenerated each time during the authorization process.
valid_until M AN The date until the token will be valid.
{
  "callback_url": "https://tpp.example.com/signed",
  "access_token": "$#@%#$%^$@#$56445641653!@#$%3",
  "valid_until": "2020-10-13T12:54:58+00:00"
}

Payment status

The "payment status" message is necessary for the TOB to get the information when the BANK proceeds with the payment. As soon as payment is finished the system sends the webhook that the payment is done, and the TPP should respond that they have received the webhook successfully.

Endpoint Method
ttps://bank-api.openbank-sandbox.tribepayments.com/bank/payment_status GET

Request

Parameter M Type Length Description
status M AN 10 The max length of the field is 10 characters. Brings back if the request was successful or there were any errors.
payment_id M N 11 Unique payment identifier. The max length of the field is 20 characters.
payment_status O AN 20 See Payment status. Empty if status = error.
{
  "status": "success",
  "payment_id": "454651545114",
  "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"
}

Webhooks

Account

Balance

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

Endpoint Method
https://BANK_DOMAIN/account_balance POST

Request

Parameter M Type Length Description
iban M AN 34 The selected IBAN number which information should be received. The length of the field is 34 characters.
{
  "iban": "GB999999999999999999"
}

Response

Parameter M Type Length Description
status M AN 10 Sends the response information if the request was successful or an error occurs. The max length of the field is 10 characters.
accounts M LIST Under this parameter all requested accounts will be listed.
id M N 20 The ID of the account. The max length of the field is 20 characters.
name M AN 20 The name of the account. The max length of the field is 20 characters.
balance M N 50 Account balance. The max length of the field is 50 characters.
currency M A 3 Currency abbreviation regarding ISO 4217. The length of the field is 3 characters.
{
  "status": "success",
  "account": {
    "id": 15922246314898,
    "name": "John Doe",
    "balance": 5000.00,
    "currency": "EUR"
  }
}

Get

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

Endpoint Method
https://BANK_DOMAIN/account POST

Request

Parameter M Type Length Description
iban M AN 34 The selected IBAN number which information should be received. The length of the fields is 34 characters.
{
  "iban": "GB999999999999999999"
}

Response

Parameter M Type Length Description
status M AN 10 Sends the response information if the request was successful or an error occurs. The max length of the value is 10 characters.
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. The length of the fields is 34 characters.
currency M A 3 Currency abbreviation regarding ISO 4217.
additional_data M LIST Listed additional data.
{
  "status": "success",
  "account": {
    "id": 15922246314898,
    "name": "John Doe",
    "iban": "GB999999999999999999",
    "currency": "EUR",
    "additional_data": []
  }
}

Get list

"Get accounts" message is initiated by the request from TPP and it is the part of the Get data flow between the BANK and TOB. TPP requests client's accounts information from TOB which requests the information from the BANK.

Endpoint Method
https://BANK_DOMAIN/accounts POST

Request

TOB sends the Headers to the required endpoint.

Response

Parameter M Type Length Description
status M AN 10 Sends the response information if the request was successful or an error occurs.
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 A 3 Currency abbreviation regarding ISO 4217.
additional_data M LIST Listed additional data.
{
  "status": "success",
  "accounts": [
    {
      "id": 15922246314898,
      "name": "John Doe",
      "iban": "GB999999999999999999",
      "currency": "EUR",
      "additional_data": []
    },
    {
      "id": 15922273037137,
      "name": "Jane Doe",
      "iban": "GB888888888888888888",
      "currency": "GBP",
      "additional_data": []
    }
  ]
}

Get payment

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

Endpoint Method
https://BANK_DOMAIN/account_payment POST

Request

Parameter M Type Length Description
payment_id M N 20 Payment identification number which details are requested.
{
   "payment_id": 15912737323223
}

Response

Parameter M Type Length Description
status M AN 10 The response status if the request was successful, or an error occurs.
payment 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.
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.
{
  "status": "success",
  "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 request from TPP. It is the part of the Get data flow between the BANK and TOB. TPP requests a selected account payments list with its information from TOB which requests the information from the BANK.

Endpoint Method
https://BANK_DOMAIN/account_payments POST

Request

Parameter M Type Length Description
iban M AN 34 International BANK account number. The length of the fields is 34 characters.
record_count O N 3 Payments count per page. Max value is 100. Default value is 10.
current_page O N 3 Default is 1. The max length of the field is 3 characters.
{
  "iban": "GB999999999999999999",
  "record_count": 15,
  "current_page": 2
}

Response

Parameter M Type Length Description
status M AN 10 The response status if the request was successful, or an error occurs. The max length of the field is 10 characters.
payments M LIST
id M N 20 The ID of the payment. The max length of the field is 20 characters.
reference M AN 30 The reference number. The max length of the field is 30 characters.
date_created M AN 10 The max length of the field is 10 characters. ISO 8601 format.
amount M N 20 The amount of the payment. The max length is 20 characters.
description M AN 255 Information about the transfer. The max length of the length is 255 characters.
additional_data M LIST
sender_data M LIST
iban M AN 34 The IBAN from which the transfer was made. The length of the field 34 characters.
account_name M AN 50 The name of the account. The length of the field is 50 characters.
account_number M AN 34 The account number. The max length is 34 characters.
sort_code M AN 6 The sort code. The max length of the field is 6 characters.
bic M AN 12 BANK identifier code from which the transfer was made. The length of the field is 12 characters.
currency M AN 3 Sender account currency code The length of the field is 3 characters.
receiver data M LIST
iban M AN 34 The IBAN to which the transfer was made. The length of the field is 34 characters.
account_name M AN 50 The name of the account. The length of the field is 50 characters.
account_number M AN 34 The account number. The max length is 34 characters.
sort_code M AN 6 The sort code. The max length of the field is 6 characters.
bic M AN 12 BANK identifier code to which the transfer was made. The length of the field is 12 characters.
currency M AN 3 Receiver account currency code The length of the field is 3 characters.
paginator M LIST Paginator details
limit M N 3 Current limitation status. the max value is 100.
current_page M N 3 The max length of the field is 3 characters.
{
  "status": "success",
  "payments": [
    {
      "id": 15910999261806,
      "reference": "BB200400490",
      "date_created": "2015-12-05",
      "amount": 5500.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": "1321654",
            "sort_code": "333444",
            "bic": "CCCGB22XXX",
            "currency": "GBP"
          }
        }
      ]
    },
    {
      "id": 15912703821936,
      "reference": "BB200420610",
      "date_created": "2017-05-05",
      "amount": 6500.00,
      "description": "Transfer from IBAN (GB888888888888888888) to IBAN (GB999999999999999999)",
      "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
  }
}

Payment

Initiate

"Payment initiation" message is initiated by the request from TPP. It is the part TPP requests TOB to initiate the payment. After the authorization is done, TOB requests BANK to initiate the payment.

Endpoint Method
https://BANK_DOMAIN/payment_initiation POST

Request

Parameter M Type Length Description
sender_iban M AN 34 The length of the field is 34 characters.
amount M N 10 The payment amount.
currency M AN 3 Currency abbreviation regarding ISO 4217.
receiver_name M A 40 The name of the receiver.
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. The max length of the field is 34 characters.
receiver_sort_code C AN 6 Required if the receiver_iban is empty. Length of the field is 6 characters.
message_for_receiver O AN 35 The max length of the field is 35 characters.
callback_url M AN - Callback URL to the TPP.
webhook-url O AN - Webhook URL to the TPP Client.
{
  "sender_iban": "GB21TRB00993587735996",
  "amount": 1500.00,
  "currency": "EUR",
  "receiver_name": "Company Ltd",
  "receiver_account_number": "00000014",
  "receiver_sort_code": "040472",
  "message_for_receiver": "Payment for goods",
  "callback_url": "https://tpp.example.com/"
}

Response

Parameter M Type Description
status M AN The max length of the field is 10 characters. Brings back if the request was successful or there were any errors.
confirmation_url M AN Confirmation URL which was generated in the BANK. The URL to which the user will be redirected to enter his confirmation.
payment_id M N Unique payment identifier. The max length of the field is 20 characters.
{
  "status": "success",
  "confirmation_url": "https://bank.example.com/confirm/?code=32321",
  "payment_id": "4GVDD4545DD"
}

Appendix

Changelog

Version Date Updates
1.0.0 August 14, 2020 Initial version.

Enum

Error code

Code Description
4000 Unknown error.
4001 Wrong request content.
4002 Internal server error.
4003 Request body is not valid JSON.
4200 Wrong credentials.
4201 Authentication required.
4202 This API action does not exist.
4203 SSL credentials not found: "SSL_CLIENT_S_DN_Email", "SSL_CLIENT_S_DN".
4300 Parameter "request_url" is missing.
4301 Parameter "request_url" is not correct.
4302 Parameter "scope" is missing.
4303 Parameter "scope" is not correct.
4304 Parameter "iban" is missing.
4305 Parameter "iban" is not correct.
4306 Selected scope is not valid for this request.

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.

Example

Initial authorization

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

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

Possible workflow after logging in

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

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

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

Security

Authentication

In order to encrypt request and response you should set these parameters to the header.

Request header

Key M Example Description
X-API-KEY M a#p#i#k#e#y Used for client authorization reasons. The API key must match the BANK's client API key. Unique for each BANK provider.
X-AUTH-TOKEN C $#s3gS#egD The token is generated during the authorization procedure after the consents are submitted. Each user has a unique token. The parameter is not required, with "Init Authorization" and with "Save Consent" messages.
X-REQUEST-ID M df455fffd43 Unique request ID.
Content-type O application/json The value is application / json.
X-SIGNATURE O d5xbk0uf.....asdlk Request signed with the Open Banking private key.

Signature

Message integrity is ensured with HTTP-Signature. For every call the signature is generated and included in headers (x-signature). Signatures are generated with SHA-256 algorithm.

$verify = openssl_verify(
    $requestContent,
    base64_decode($signature),
    $publicKey,
    OPENSSL_ALGO_SHA256
);

if (1 === $verify) {
    // signature is correct
}

Notation

Abbreviation

Abbreviation Description
ASPSP This is the account servicing provider.
BANK Account Servicing Payment Service Provider (ASPSP) and Payment Initiation Service Provider (PISP).
BIC BANK Identifier Code.
Consent Consent is the agreement given by the customer to the TPP to retrieve the PSU's data from the BANK. Consent is stored and verified by the BANK, but approved by the PSU. Consent may have different characteristics, like recurrence, expiration, etc.
PSU Payment Service User.
SCA The process of using a strong (2-factor) identification method to identify the customer.
TOB Tribe Open Banking.
TPP Third-Party Provider (TPP) is a provider of an application that the PSU uses and that is not offered by the BANK. TPP is the client/consumer of the API and acts on behalf of the PSU.

Parameter requirement

Notation Description
M Mandatory
O Optional
C Conditional

Type

Notation Description
A 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 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 the 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.

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.

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

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

  7. The BANK responds TOB with the confirmation URL to which the user needs to be redirected and 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.