Introduction

Overview

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

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 Security section 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 headers
  • Request format
  • Response format

URL

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

Request headers

Required headers can be checked in the Security section.

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
code M AN 255 Possible error codes Mandatory if any error has occurred.
title O AN - Title of the error.
timestamp M AN 25 Timestamp of when the error occurred in ISO 8601.
requestId M AN 16 UUID of the request.
additionalErrors O LIST - List of additional errors .
additionalErrors[*].code M AN 255 Possible error codes
additionalErrors[*].title O AN - Title of the error.
additionalErrors[*].details O AN - Longer description of the error.

Webhooks

Webhooks are HTTP callbacks triggered by an event in a web application. Open Banking BANK API uses webhooks mainly to pass verified requests from TPP to fetch PSU's data or initiate payment.

Workflow for webhooks:

bank webhook diagram

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

Request

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

Response

Response can be one of 2 types:

  • Success response
  • Error response
Success

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

Error

Error response to webhook request is the same for all the actions, and ASPSP should implement and return it correctly for debugging purposes. The format is:

Parameter Requirement Type Length Description
code M AN 255 Mandatory if any error has occurred.
title O AN - Title of the error.
timestamp M AN 25 Timestamp of when the error occurred in ISO 8601.
requestId O AN 16 UUID of the request.

Actions

[[OPENAPI]]

Webhooks

[[WEBHOOKS-OPENAPI]]

Security

Authentication

In order to secure requests the 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 payment.
X-Request-Id M 1af7b333-7a06-41b1-8a61-e9a29fd069bc Unique request ID - must be valid UUID.
Content-Type O application/json API uses the JSON data format in the request body.
X-Signature M d5xbk0uf.....asdlk Request signed with the Open Banking private key.

Signature

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

An example of signature verification:

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

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

Appendix

Changelog

[[CHANGELOG]] |

Enum

Error code

Code Status code Description
INTERNAL_SERVER_ERROR 500 Internal error
PAYMENT_SCHEME_INVALID 400 Provided payment scheme is invalid for current ASPSP
ASPSP_UNKNOWN_ERROR 502 Request to ASPSP failed
PARAMETER_NOT_CONSISTENT 400 URL path or query parameter is invalid
FORMAT_ERROR 400 Wrong request content
HEADERS_ERROR 400 Headers error
SERVICE_BLOCKED 403 Access denied
RESOURCE_UNKNOWN 404 Resource unknown
WRONG_CREDENTIALS 401 Wrong credentials
AUTHENTICATION_REQUIRED 401 Authentication required
API_ACTION_DOES_NOT_EXIST 401 This API action does not exist
SSL_CREDENTIALS_NOT_FOUND 401 SSL credentials not found: "SSL_CLIENT_S_DN_Email", "SSL_CLIENT_S_DN"
REQUEST_ID_NOT_UUID 401 Header "X-Request-Id" is not valid UUID

Additional error codes

Code Description
ASPSP_ERROR_DESC ASPSP error description
EXTRA_FIELDS_PROVIDED Unknown fields provided in the request content
INVALID_DATE_FORMAT Invalid "date" format
INVALID_MODEL_TYPE Field {{ fieldName }} type is invalid
INVALID_PAYMENT_ID_FORMAT Invalid "paymentId" format
INVALID_PAYMENT_STATUS_FORMAT Invalid "paymentStatus" format
AUTHORIZATION_REQUEST_URL_DOES_NOT_EXIST Parameter "requestUrl" is missing
AUTHORIZATION_REQUEST_URL_NOT_VALID Parameter "requestUrl" is not correct
AUTHORIZATION_SCOPE_DOES_NOT_EXIST Parameter "scope" is missing
AUTHORIZATION_SCOPE_NOT_CORRECT Parameter "scope" is not correct
AUTHORIZATION_IBAN_NOT_VALID Parameter "iban" is not correct
AUTHORIZATION_SELECTED_WRONG_SCOPE Selected scope is not valid for this request
AUTHORIZATION_ACCOUNT_IDENTIFIERS_MISSING Account identifiers missing
AUTHORIZATION_TOKEN_NOT_VALID Invalid "accessToken" format

Payment status

Status ISO 20022 string Description
ACCC AcceptedSettlementCompleted Settlement on the creditor's account has been completed. This code is not supported by most banks.
ACCP AcceptedCustomerProfile Preceding check of technical validation was successful. The customer profile check was also successful.
ACSC AcceptedSettlementCompleted Settlement on the debtor’s account has been completed.
ACSP AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
ACTC AcceptedTechnicalValidation Authentication as well as syntactical and semantical validation are successful. This is usually regarded as a pending status, waiting for SCA.
ACWC AcceptedWithChange Instruction is accepted but a change will be made, such as date or remittance not sent.
ACWP AcceptedWithoutPosting Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account.
RCVD Received Payment initiation has been received by the receiving agent.
PDNG Pending Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status updates will be performed.
RJCT Rejected Payment initiation or individual transaction included in the payment initiation has been rejected.
CANC Canceled Payment initiation has been cancelled before execution.
ACFC AcceptedFundsChecked Preceding check of technical validation and customer profile was successful and an automatic funds check was positive.
PATC PartiallyAcceptedTechnicalCorrect The payment initiation needs multiple authentications, where some but not yet all have been performed. Syntactical and semantical validations are successful.
PART PartiallyAccepted A number of transactions have been accepted, whereas a number of other transactions have not yet been granted the 'accepted' status.

Payment schemes

Scheme Description
FPS Faster Payments is used for payments between United Kingdom BANKs. Used by default for UK payments.
BACS Usable for payments in the United Kingdom.
CHAPS Usable for payments in the United Kingdom.
SCTI Used for instant SEPA payments if supported by BANKs.
SCT Used for SEPA payments. Used as the default for EU payments.
SWIFT SWIFT (Society for Worldwide Interbank Financial Telecommunication), used for international and multicurrency payments.

Balance type

This definition is following ISO20022 logic for defining balance types.

Type Description
openingBooked Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report.
interimAvailable Available balance calculated in the course of the account servicer’s business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. Available balance typically includes credit line.
interimBooked Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
forwardAvailable Forward available balance of money that is at the disposal of the account owner on the date specified.
nonInvoiced Only for card accounts, to be defined yet.

Scopes

Scope Service Description
accounts AISP Get PSU account list and details
accounts.balances AISP Get PSU account's balances
accounts.transactions AISP Get PSU account's transactions
payments.single PISP Single Payment initiation
payments.bulk PISP Bulk Payment initiation
funds_confirmations CBPII Confirmation of funds

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
CBPII Card Based Payment Instrument Issuer
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
OBJECT JSON object
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 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 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.