Introduction

Overview

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

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

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

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

🛈 The terms and their descriptions can be found in the Notation section.

Security

Please make sure to read the appendix Security before proceeding to use this API.

Version

To see the current version and details of recent changes, please see the Changelog.

Interaction

API interaction consists of following mechanisms:

  • Actions - HTTP(s) request initiated by API client (you) and sent to Tribe.
  • Webhooks - HTTP(s) request initiated by Tribe and sent to API client (you).

Actions

This API provides list of actions for retrieving and manipulating data entities.

Workflow for actions is:

bank action diagram

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

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

  • URL
  • Request format
  • Response format

URL

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

Request

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

Response

Response can be one of 2 types:

  • Success response
  • Error response
Success

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

Error

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

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

Webhooks

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

Workflow for webhooks:

bank webhook diagram

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

Actions

Authorization

Initial

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

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

Request

Parameter M Type Length Description
request_url M AN - URL with Oauth2 authorization information
{  "request_url": "https://bank.example.com/obb/authorize?client_id=gt34tg3tg34tg&redirect_uri=http%3A%2F%2Ftpp.example.com%2Ftoken&state=1111111&response_type=code&scope=account.list+account.details" }

Response

Parameter M Type Length Description
tpp_name M AN - TPP name
tpp_registration_number M AN - TPP registration number
scopes M LIST - Scopes to be approved
cancel_url M AN - URL for cancelling authorization
{  "tpp_name": "TPP name",
   "tpp_registration_number": "UK-145441",  
   "scopes": [  
       "account.list", 
       "payment.init"  
    ],  
   "cancel_url": "https://tpp.example.com/authorize/cancel?hash=JFB45sdasdJHNFDD554"  }

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

Endpoint Method
https://bank-api.openbank-sandbox.tribepayments.com/bank/consent POST
Parameter M Type Length Description
scopes M LIST - List of approved consents
request_url M AN - Used authorization URL
ibans O LIST List of scope approved IBANs
account_ids O LIST List of scope approved account IDs
account_numbers O LIST List of scope approved account number (possibly in combination with sort code)
{
  "scopes": [
    "payment.init",
    "account.list"
  ],
  "request_url": "https://bank.example.com/obb/authorize?client_id=gt34tg3tg34tg&redirect_uri=http%3A%2F%2Ftpp.example.com%2Ftoken&state=1111111&response_type=code&scope=account.list+account.details",
  "ibans": [
    "GB67BARC20037893545993",
    "GB66BARC20040438475453",
    "GB65BARC20040454867986"
  ],
  "account_ids": [
    "6d900676edf07ce90cdb30f1529a1e3c02095"
  ],
  "account_numbers": [
    "123456",
    "555987"
  ]
}
Parameter M Type Description
callback_url M AN Callback URL to redirect the user back to the TPP.
access_token M AN A generated token which will be used to access user data.
valid_until M AN The date until the token will be valid.
{
  "callback_url": "https://tpp.example.com/signed",
  "access_token": "$#@%#$%^$@#$56445641653!@#$%3",
  "valid_until": "2020-10-13T12:54:58+00:00"
}

Revoke token

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

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

Request

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

Response

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

Payment status

In case of change in payment status, Bank should inform TPP about it by calling this endpoint.

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

Request

Parameter M Type Length Description
payment_id M AN - ID of Payment
payment_status M N - Status of Payment
{
  "payment_id": "8fecdd380d7d1924f97300aa323",
  "payment_status": 4
}

Response

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

Webhooks

Account

Balance

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

Endpoint Method
https://BANK_DOMAIN/account_balance POST

Request

Parameter M Type Length Description
iban M AN 34 Selected IBAN
{
  "iban": "GB63BARC20038416599456"
}

Response

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

Get

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

Endpoint Method
https://BANK_DOMAIN/account POST

Request

Parameter M Type Length Description
iban M AN 34 Selected IBAN
{
  "iban": "GB63BARC20038416599456"
}

Response

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

Get list

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

Endpoint Method
https://BANK_DOMAIN/accounts POST

Response

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

Get payment

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

Endpoint Method
https://BANK_DOMAIN/account_payment POST

Request

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

Response

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

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

Get payments

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

Endpoint Method
https://BANK_DOMAIN/account_payments POST

Request

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

Response

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

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

Payment

Initiate

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

Endpoint Method
https://BANK_DOMAIN/payment_initiation POST

Request

Parameter M Type Length Description
sender_iban M AN 34 IBAN of sender account
amount M N 10 Payment amount
currency M AN 3 Currency abbreviation according to ISO 4217
receiver_name M A 40 Name of the receiver
receiver_iban C AN 34 If receiver_iban is provided - receiver_account_number and receiver_sort_code fields can be empty.
receiver_account_number C N 34 Required if the receiver_iban is empty.
receiver_sort_code C AN 6 Required if the receiver_iban is empty.
message_for_receiver O AN 35
callback_url M AN - Callback URL to the TPP
{
  "sender_iban": "GB07BARC20040143155262",
  "amount": 1500.00,
  "currency": "EUR",
  "receiver_name": "Company Ltd",
  "receiver_account_number": "00000014",
  "receiver_sort_code": "040472",
  "message_for_receiver": "Payment for goods",
  "callback_url": "https://tpp.example.com/"
}

Response

Parameter M Type Description
status M AN Response status indicator
confirmation_url M AN The URL to which the user will be redirected to enter his confirmation.
payment_id M AN Unique payment identifier
{
  "status": "success",
  "confirmation_url": "https://bank.example.com/confirm/?code=32321",
  "payment_id": "4GVDD4545DD"
}

Callback URL parameters for redirect after user accesses confirmation_url and BANK performs redirect to callback_url from request content:

Parameter M Type Length Description
status M N - Status of payment after confirmation.
payment_id M AN - ID of payment
message C AN - Message with description in case of error.

Revoke token

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

Endpoint Method
https://BANK_DOMAIN/revoke_token POST

Request

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

Response

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

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

Direct Webhooks

Payment

Initiate

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

Endpoint Method
https://BANK_DOMAIN/payment_initiation POST

Request

Parameter M Type Length Description
sender_iban M AN 34 IBAN of sender account
amount M N 10 Payment amount
currency M AN 3 Currency abbreviation according to ISO 4217
receiver_name M A 40 Name of the receiver
receiver_iban C AN 34 If receiver_iban is provided - receiver_account_number and receiver_sort_code fields can be empty.
receiver_account_number C N 34 Required if the receiver_iban is empty.
receiver_sort_code C AN 6 Required if the receiver_iban is empty.
message_for_receiver O AN 35
callback_url M AN - Callback URL to the TPP
{
  "sender_iban": "GB07BARC20040143155262",
  "amount": 1500.00,
  "currency": "EUR",
  "receiver_name": "Company Ltd",
  "receiver_account_number": "00000014",
  "receiver_sort_code": "040472",
  "message_for_receiver": "Payment for goods",
  "callback_url": "https://tpp.example.com/"
}

Response

Parameter M Type Description
status M AN Response status indicator
confirmation_url M AN The URL to which the user will be redirected to enter his confirmation.
payment_id M AN Unique payment identifier
{
  "status": "success",
  "confirmation_url": "https://bank.example.com/confirm/?code=32321",
  "payment_id": "4GVDD4545DD"
}

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.
4004 Unknown bank
4005 Unreachable TPP
4200 Wrong credentials
4201 Authentication required
4202 Access token not found.
4202 This API action does not exist.
4203 SSL credentials not found: "SSL_CLIENT_S_DN_Email", "SSL_CLIENT_S_DN"
4204 Header "X-Request-Id" is not valid UUID
4300 Parameter "request_url" is missing.
4301 Parameter "request_url" is not correct.
4302 Parameter "scope" is missing.
4303 Parameter "scope" is not correct.
4305 Parameter "iban" is not correct.
4306 Selected scope is not valid for this request.
4307 Account identifiers missing.

Payment 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

Example

Initial authorization

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

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

Possible workflow after logging in

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

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

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

Security

Authentication

In order to secure requests these following parameters are used in headers.

Request header

Key M Example Description
X-Api-Key M a#p#i#k#e#y Used for client authorization reasons. The API key must match the BANK's client API key. Unique for each BANK provider.
X-Auth-Token C $#s3gS#egD The token is generated during the authorization procedure after the consents are submitted. Each user has a unique token. Not required when not using user data. Not used for Direct webhooks.
X-Request-Id M 1af7b333-7a06-41b1-8a61-e9a29fd069bc Unique request ID - must be valid UUID
Content-Type O application/json API uses JSON data format.
X-Signature O d5xbk0uf.....asdlk Request signed with the Open Banking private key.

Signature

Message integrity is ensured with custom signature header X-Signature. Signatures are generated with SHA-256 algorithm.

Example of verification:

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

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

Notation

Abbreviation

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

Parameter requirement

Notation Description
M Mandatory
O Optional
C Conditional

Type

Notation Description
A Alphabetical inputs (A-Z a-z)
AN Alphanumeric inputs (0-9 A-Z a-z .!@)
LIST
N Numeric inputs (0-9)

Workflow

Authorization

Activity

Authorization activity

Sequence

authorization sequence

Authorization is necessary to provide TPP consents to access accounts and their information in the BANK. As long as consents are valid this procedure will not be repeated, except for the authorization in the payments flow.

The workflow of the authorization:

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

  1. User of TPP application accesses BANK authorization website.

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

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

  4. The user should be navigated to the authorization in the selected BANK.

  5. Was the authorization successful?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.
  6. Have the PSU approved scopes?

    If "no":

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

    If "yes":

    1. BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.

    2. The BANK redirects the user back to the TPP site with authorization data in URL query.

⚠ Warning!
All the requested consents must be approved: not more and not less. Otherwise, the authorization procedure will not be successful.

Get data

Activity

activity get info

Sequence

get accounts sequence

Get data flow is necessary for the TPP to retrieve information. The TPP can request PSU accounts list, account details, payment list etc. Access to information depends on which scopes were approved on the BANK side, e.g. if the TPP does not have consent for the account details, account details will no be provided for the TPP. Length of validity is provided in response with access token.

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

The workflow of the get info:
  1. BANK receives request to provide PSU data from TOB.

  2. BANK sends the response with the requested information to the TOB.

Payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

Payment flow has 2 variants:

  • One-time use consent, which requires whole authorization flow, is similar to the authorization flow above, actions are identical up to point 6 and token is expired after use.

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

Workflow
  1. User of TPP application accesses BANK authorization website.

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

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

  4. The user should be navigated to the authorization in the selected BANK.

  5. Was the authorization successful?

    If "no":

    1. BANK cancels the flow, redirects the user back to TPP and sends the cancellation information.
  6. Have the PSU approved scopes?

    If "no":

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

    If "yes":

    1. BANK calls "Save consent" in TOB and receives access token to use for PSU account and redirect URL.

    2. The BANK redirects the user back to the TPP site with authorization data in URL query.

⚠ Warning!
All the requested consents must be approved: not more and not less. Otherwise, the authorization procedure will not be successful.
  1. BANK receives call for payment initiation and performs action necessary to execute payment.

  2. BANK checks if payment can be executed (e.g. balance is enough)?

    If "not":

    1.  BANK cancels the flow, returns error information.
    
  3. BANK responds with basic payment information and confirmation_url.

  4. User access confirmation_url to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?

    If "no":

    1. The payment will be cancelled, and the user will be redirected back to TPP callback_url and appropriate status and message fields in redirect URL query.

    If "yes":

    1. Payment proceeds and user is redirected back to TPP callback_url with appropriate status, payment_id in redirect URL query.
  5. Was there any reason to decline the payment?

    If "yes":

    1. Flow is canceled, user is redirected back to TPP callback_url with appropriate cancel status, payment_id and message fields in redirect URL query.

Direct payment

Workflow

uml_act_payments

Sequence

uml_sec_payments

Workflow
  1. BANK receives call for payment initiation and performs action necessary to execute payment.

  2. BANK checks if payment can be executed (e.g. balance is enough)?

    If "not":

    1.  BANK cancels the flow, returns error information.
    
  3. BANK responds with basic payment information and confirmation_url.

  4. User access confirmation_url to confirm payment with the selected tool (e.g. OTP PIN2). Did the user confirm the payment?

    If "no":

    1. The payment will be cancelled, and the user will be redirected back to TPP callback_url and appropriate status and message fields in redirect URL query.

    If "yes":

    1. Payment proceeds and user is redirected back to TPP callback_url with appropriate status, payment_id in redirect URL query.
  5. Was there any reason to decline the payment?

    If "yes":

    1. Flow is canceled, user is redirected back to TPP callback_url with appropriate cancel status, payment_id and message fields in redirect URL query.