Glossary Index

API Glossary

API

The terms API (Application Programming Interface) and Endpoint are used somewhat interchangeably.

However, an API normally refers to a group of Endpoints.

An endpoint has a unique URL path and HTTP verb (GET, POST, PUT, DELETE etc).

When we POST a Swagger file to the Create Endpoint endpoint, we are in fact creating a set of Endpoints that have a common Tag. Tags are used to group Endpoints in the API Explorer and filter the Endpoints in the Resource Doc endpoints.

Endpoints can also be grouped together in Collections.

See also Endpoint

Go Back to API APIs

API Collection

An API Collection is a collection of endpoints grouped together for a certain purpose.

Having read access to a Collection does not constitute execute access on the endpoints in the Collection.

(Execute access is governed by Entitlements to Roles - and in some cases, Views.)

Collections can be created and shared. You can make a collection non-sharable but the default is sharable.

Your "Favourites" in API Explorer is actually a collection you control named "Favourites".

To share a Collection (e.g. your Favourites) just click on your Favourites in the API Explorer and share the URL in the browser. If you want to share the Collection via an API, just share the collection_id with a developer.

If you share a Collection it can't be modified by anyone else, but anyone can use it as a basis for their own Favourites or another collection.

There are over 13 endpoints for controlling Collections.
Some of these endpoints require Entitlements to Roles and some operate on your own personal collections such as your favourites.

API Tag

All OBP API relevant docs, eg: API configuration, JSON Web Key, Adapter Info, Rate Limiting

API.Access Control

Access Control is achieved via the following mechanisms in OBP:

  • APIs are enabled in Props. See the README.md

  • Consumers (Apps) are granted access to Roles and Views via Scopes (WIP)

See here for related endpoints and documentation.

  • Users are granted access to System or Bank Roles via Entitlements.

See here for related endpoints and documentation.

Users may request Entitlement Requests here

Entitlements and Entitlement Requests can be managed in the OBP API Manager.

  • Users are granted access to Customer Accounts, Transactions and Payments via Views.

See here for related endpoints and documentation.

User Views can be managed via the OBP Sofit Consent App.

OBP Access Control Image

API.correlation_id

Example value: 1flssoftxq0cr1nssr68u0mioj

Description: A string generated by OBP-API that MUST uniquely identify the API call received by OBP-API. Used for debugging and logging purposes. It is returned in header to the caller.

ATM.atm_type

Example value:

Description: no-description-provided

ATM.attribute_id

Example value: atme-9a0f-4bfa-b30b-9003aa467f51

Description: A string that MUST uniquely identify the ATM on this OBP instance.

ATM.balance_inquiry_fee

Example value:

Description: no-description-provided

ATM.branch_identification

Example value:

Description: no-description-provided

ATM.cash_withdrawal_international_fee

Example value:

Description: no-description-provided

ATM.cash_withdrawal_national_fee

Example value:

Description: no-description-provided

ATM.has_deposit_capability

Example value: true

Description: no-description-provided

ATM.is_accessible

Example value: true

Description: no-description-provided

ATM.located_at

Example value:

Description: no-description-provided

ATM.location_categories

Example value: ["ATBI","ATBE"]

Description: no-description-provided

ATM.minimum_withdrawal

Example value: 5

Description: minimum withdrawal at this ATM

ATM.name

Example value: Atm by the Lake

Description: The name of the ATM

ATM.notes

Example value: ["String1","String2"]

Description: no-description-provided

ATM.services

Example value: ["ATBP","ATBA"]

Description: no-description-provided

ATM.site_identification

Example value:

Description: no-description-provided

ATM.site_name

Example value:

Description: no-description-provided

Account

The thing that tokens of value (money) come in and out of.
An account has one or more owners which are Users.
In the future, Customers may also be owners.
An account has a balance in a specified currency and zero or more transactions which are records of successful movements of money.

Go Back to Account APIs

Account Access

Account Access is OBP View system. The Account owners can create the view themselves.
And they can grant/revoke the view to other users to use their view.

Go Back to Account Access APIs

Account.account_id

An identifier for the account that MUST NOT leak the account number or other identifier nomrally used by the customer or bank staff.
It SHOULD be a UUID. It MUST be unique in combination with the BANK_ID. ACCOUNT_ID is used in many URLS so it should be considered public.
(We do NOT use account number in URLs since URLs are cached and logged all over the internet.)
In local / sandbox mode, ACCOUNT_ID is generated as a UUID and stored in the database.
In non sandbox modes (Kafka etc.), ACCOUNT_ID is mapped to core banking account numbers / identifiers at the South Side Adapter level.
ACCOUNT_ID is used to link Metadata and Views so it must be persistant and known to the North Side (OBP-API).

Example value: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

Account.account_routing_address

Example value: DE91 1000 0000 0123 4567 89

Description: An identifier that conforms to account_routing_scheme / accountRoutingScheme

Account.account_routing_scheme

Example value: IBAN

Description: The scheme that the account_routing_address / accountRoutingAddress is an example of.

Account.iban

Example value: DE91 1000 0000 0123 4567 89

Description: MUST uniquely identify the bank account globally.

Account.owner

Example value: SusanSmith

Description: A username that is the owner of the account.

Account.queryTagsExample

Example value: Card,Debit

Description: This field is only used for OBP to distinguish the debit accounts, card accounts ...

Adapter.Akka.Intro

Use Akka as an interface between OBP and your Core Banking System (CBS).

For an introduction to Akka see here

The OBP Akka interface allows integrators to write Java or Scala Adapters (any JVM language with Akka support)
respond to requests for data and services from OBP.

For the message definitions see here

Installation Prerequisites

  • You have OBP-API running.

  • Ideally you have API Explorer running (the application serving this page) but its not necessary - you could use any other REST client.

  • You might want to also run API Manager as it makes it easier to grant yourself roles, but its not necessary - you could use the API Explorer / any REST client instead.

Create a Customer User and an Admin User

  • Register a User who will use the API as a Customer.
  • Register another User that will use the API as an Admin. The Admin user will need some Roles. See here. You can bootstrap an Admin user by editing the Props file. See the README for that.

Add some authentication context to the Customer User

  • As the Admin User, use the Create Auth Context endpoint to add one or more attributes to the Customer User.
    For instance you could add the name/value pair CUSTOMER_NUMBER/889763 and this will be sent to the Adapter / CBS inside the AuthInfo object.

Now you should be able to use the Get Auth Contexts endpoint to see the data you added.

Write or Build an Adapter to respond to the following messages.

When getting started, we suggest that you implement the messages in the following order:

1) Core (Prerequisites) - Get Adapter, Get Banks, Get Bank

Now you should be able to use the Adapter Info endpoint

Now you should be able to use the Get Banks endpoint

Now you should be able to use the Get Bank endpoint

2) Get Customers by USER_ID

Now you should be able to use the Get Customers endpoint.

3) Get Accounts

The above messages should enable at least the following endpoints:

4) Get Account

The above message should enable at least the following endpoints:

5) Get Transactions

6) Manage Counterparties

7) Get Transaction Request Types

  • This is configured using OBP Props - No messages required

This glossary item is Work In Progress.

Adapter.Kafka.Intro

Use Kafka as an interface between OBP and your Core Banking System (CBS).

For an introduction to Kafka see here

Installation Prerequisites

  • You have OBP-API running and it is connected to a Kafka installation.
    You can check OBP -> Kafka connectivity using the "loopback" endpoint.

  • Ideally you have API Explorer running (the application serving this page) but its not necessary - you could use any other REST client.

  • You might want to also run API Manager as it makes it easier to grant yourself roles, but its not necessary - you could use the API Explorer / any REST client instead.

Create a Customer User and an Admin User

  • Register a User who will use the API as a Customer.
  • Register another User that will use the API as an Admin. The Admin user will need some Roles. See here. You can bootstrap an Admin user by editing the Props file. See the README for that.

Add some authentication context to the Customer User

  • As the Admin User, use the Create Auth Context endpoint to add one or more attributes to the Customer User.
    For instance you could add the name/value pair CUSTOMER_NUMBER/889763 and this will be sent to the Adapter / CBS inside the AuthInfo object.

Now you should be able to use the Get Auth Contexts endpoint to see the data you added.

Write or Build an Adapter to respond to the following messages.

When getting started, we suggest that you implement the messages in the following order:

1) Core (Prerequisites) - Get Adapter, Get Banks, Get Bank

Now you should be able to use the Adapter Info endpoint

Now you should be able to use the Get Banks endpoint

Now you should be able to use the Get Bank endpoint

2) Core (Authentications) -The step1 Apis are all anonymous access. If you need to link bank customer data to the obp user,
Then you need link OBP user with Bank user/customer using the Create User Auth Context. Also
check the description for this endpoint. Once you create the user-auth-context for one user, then these user-auth-context key value pair
can be propagated over connector message. Than the Adapter can use it to map OBP user and Bank user/customer.

Now you should be able to use the Refresh User endpoint

3) Customers for logged in User

Now you should be able to use the Get Customers endpoint.

4) Get Accounts

Now you should already be able to use the Get Accounts at Bank (IDs only). endpoint.

The above messages should enable at least the following endpoints:

5) Get Account

The above message should enable at least the following endpoints:

6) Get Transactions

7) Manage Counterparties

8) Get Transaction Request Types

  • This is configured using OBP Props - No messages required

9) Get Challenge Threshold (CBS)

10) Make Payment (used by Create Transaction Request)

11) Get Transaction Requests.

12) Generate Security Challenges (CBS)

13) Answer Security Challenges (Validate)

  • Optional / Internal OBP (No additional messages required)

14) Manage Counterparty Metadata

  • Internal OBP (No additional messages required)

15) Get Entitlements

  • Internal OBP (No additional messages required)

16) Manage Roles

  • Internal OBP (No additional messages required)

17) Manage Entitlements

  • Internal OBP (No additional messages required)

18) Manage Views

  • Internal OBP (No additional messages required)

19) Manage Transaction Metadata

  • Internal OBP (No additional messages required)

Adapter.Stored_Procedure.Intro

Use Stored_Procedure as an interface between OBP and your Core Banking System (CBS).

For an introduction to Stored Procedures see here

Installation Prerequisites

  • You have OBP-API running and it is connected to a stored procedure related database.
  • Ideally you have API Explorer running (the application serving this page) but its not necessary - you could use any other REST client.
  • You might want to also run API Manager as it makes it easier to grant yourself roles, but its not necessary - you could use the API Explorer / any REST client instead.

Adapter.authInfo

authInfo is a JSON object sent by the Connector to the Adapter so the Adapter and/or Core Banking System can
identify the User making the call.

The authInfo object contains several optional objects and fields.

Please see the Message Docs for your connector for the current JSON structure. The following serves as a guide:

  • userId is the user_id as generated by OBP
  • username can be chosen explicitly to match an existing customer number (not recommended)
  • linkedCustomers is a list of Customers the User is explicitly linked to. Use the Create User Customer Link endpoint to populate this data.
  • userAuthContexts may contain the customer number or other tokens in order to boot strap the User Customer Links
    or provide an alternative method of tagging the User with an authorisation context.
    Use the Create UserAuthContext endpoint to populate this data.
  • cbsToken is a token used by the CBS to identify the user's session. Either generated by the CBS or Gateway.
  • isFirst is a flag that indicates that OBP should refresh the user's list of accounts from the CBS (and flush / invalidate any User's cache)
  • correlationId just identifies the API call.
  • authViews are entitlements given by account holders to third party users e.g. Sam may grant her accountant Jill read only access to her business account. See the Create View endpoint

authinfo_annotated_1

Adapter.brand

Example value: SusanSmith

Description: The name on the physical card

Adapter.card_attribute_id

Example value: b4e0352a-9a0f-4bfa-b30b-9003aa467f50

Description: A string that MUST uniquely identify the card attribute on this OBP instance. It SHOULD be a UUID.

Adapter.card_attribute_name

Example value: OVERDRAFT_START_DATE

Description: The Card attribute name

Adapter.card_attribute_value

Example value: 2012-04-23

Description: The card attribute values

Adapter.card_id

Example value: 36f8a9e6-c2b1-407a-8bd0-421b7119307e

Description: A string that MUST uniquely identify the card on this OBP instance. It SHOULD be a UUID.

Adapter.card_number

Example value: 364435172576215

Description: The number of the physical card

Adapter.card_type

Example value: Credit

Description: The type of the physical card. eg: credit, debit ...

Adapter.cbsToken

Example value: FYIUYF6SUYFSD

Description: A token provided by the Gateway for use by the Core Banking System

Adapter.cvv

Example value: SusanSmith

Description: The name on the physical card

Adapter.expiry_month

Example value: 01

Description: The expiry month of the card

Adapter.expiry_year

Example value: 2023

Description: The expiry year of the card

Adapter.issue_number

Example value: 1

Description: The issue number of the physical card, eg 1,2,3,4 ....

Adapter.key

Example value: CustomerNumber

Description: This key should be used with Adapter.value together. They are a pair.

Adapter.limit

Example value: 100

Description: The limit in pagination

Adapter.name_on_card

Example value: SusanSmith

Description: The name on the physical card

Adapter.offset

Example value: 100

Description: The offset in pagination

Adapter.provider_id

Example value: Chris

Description: The provider id of the user which is equivalent to the username.

Adapter.serial_number

Example value: 1324234

Description: The serial number of the physical card, eg 1123.

Adapter.value

Example value: 5987953

Description: This key should be used with Adapter.key together. They are a pair.

Age

The user Age

ApiCollection.apiCollectionId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A string that MUST uniquely identify the session on this OBP instance, can be used in all cache.

ApiCollection.apiCollectionName

Example value: Favourites

Description: Name of the ApiCollection

ApiCollectionEndpoint.apiCollectionEndpointId

Example value: 8uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A string that MUST uniquely identify the session on this OBP instance, can be used in all cache.

ApiCollectionEndpoint.operationId

Example value: OBPv4.0.0-getBanks

Description: A uniquely identify the obp endpoint on OBP instance, you can get it from Get Resource endpoints.

Attribute.name

Example value: STATUS

Description: Transaction attribute name

Attribute.type

Example value: STRING

Description: Transaction attribute type.

Attribute.value

Example value: closed

Description: Transaction attribute value.

Authentication.provider

Example value: http://127.0.0.1:8080

Description: The Provider authenticating this User

Bank

A Bank (aka Space) represents a financial institution, brand or organizational unit under which resources such as endpoints and entities exist.

Both standard entities (e.g. financial products and bank accounts in the OBP standard) and dynamic entities and endpoints (created by you or your organisation) can exist at the Bank level.

For example see Bank/Space level Dynamic Entities and Bank/Space level Dynamic Endpoints

The Bank is important because many Roles can be granted at the Bank level. In this way, it's possible to create segregated or partitioned sets of endpoints and data structures in a single OBP instance.

A User creating a Bank (if they have the right so to do), automatically gets the Entitlement to grant any Role for that Bank. Thus the creator of a Bank / Space becomes the "god" of that Bank / Space.

Basic attributes for the bank resource include identifying information such as name, logo and website.

Using the OBP endpoints for bank accounts it's possible to view accounts at one Bank or aggregate accounts from all Banks connected to the OBP instance.

See also Props settings named "brand".

Go Back to Bank APIs

Bank.bank_id

An identifier that uniquely identifies the bank or financial institution on the OBP-API instance.

It is typically a human (developer) friendly string for ease of identification.

It SHOULD NOT contain spaces.

In sandbox mode it typically has the form: "financialinstitutuion.sequencennumber.region.language". e.g. "bnpp-irb.01.it.it"

For production, it's value could be the BIC of the institution.

Example value: gh.29.uk

Bank.bank_id

Example value: gh.29.uk

Description: A string that MUST uniquely identify the bank on this OBP instance. It COULD be a UUID but is generally a short string that easily identifies the bank / brand it represents.

Bank.bank_routing_address

Example value: GENODEM1GLS

Description: An identifier that conforms to bank_routing_scheme / bankRoutingScheme

Bank.bank_routing_scheme

Example value: BIC

Description: The scheme that the bank_routing_address / bankRoutingAddress is an example of.

Branch

The bank branches, it contains the address, location, lobby, drive_up of the Branch.

Go Back to Branch APIs

Branch.branch_id

Example value: DERBY6

Description: Uniquely identifies the Branch in combination with the bankId.

Branch.branch_routing_address

Example value: DERBY6

Description: An address that conforms to branch_routing_scheme / branchRoutingScheme

Branch.branch_routing_scheme

Example value: BRANCH-CODE

Description: The scheme that the branch_routing_address / branchRoutingAddress is an example of.

ChallengeAnswer.challengeId

Example value: 123chaneid13-6d02-40e3-a129-0b2bf89de9f0

Description: MUST uniquely identify the challenge globally.

ChallengeAnswer.hashOfSuppliedAnswer

Example value: a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3

Description: Sha256 hash value of the ChallengeAnswer.challengeId

Connector

In OBP, most internal functions / methods can have different implementations which follow the same interface.

These functions are called connector methods and their implementations.

The default implementation of the connector is the "mapped" connector.

It's called "mapped" because the default datasource on OBP is a relational database, and access to that database is always done through an Object-Relational Mapper (ORM) called Mapper (from a framework we use called Liftweb).

[=============]                                                                     [============]       [============]
[.............]                                                                     [            ]       [            ]
[...OBP API...] ===> OBP Endpoints call connector functions (aka methods) ===>      [  Connector ] ===>  [  Database  ]
[.............]          The default implementation is called "Mapped"              [  (Mapped)  ]       [  (Adapter) ]
[=============]              The Mapped Connector talks to a Database               [============]       [============]

However, there are multiple available connector implementations - and you can also mix and create your own.|

E.g. Kafka

[=============]                              [============]       [============]     [============]       [============]
[             ]                              [            ]       [            ]     [            ]       [            ]
[   OBP API   ] ===> Kafka Connector   ===>  [  Kafka     ] ===>  [  Kafka     ]     [  OBP Kafka ]  ===> [  CBS       ]
[             ]      Puts OBP Messages       [  Connector ]       [  Cluster   ]     [  Adapter   ]       [            ]
[=============]       onto a Kafka           [============]       [============]     [============]       [============]

You can mix and match them using the Star connector and you can write your own in Scala. You can also write Adapters in any language which respond to messages sent by the connector.

we use the term "Connector" to mean the Scala/Java/Other JVM code in OBP that connects directly or indirectly to the systems of record i.e. the Core Banking Systems, Payment Systems and Databases.

A "Direct Connector" is considered to be one that talks directly to the system of record or existing service layer.

i.e. API -> Connector -> CBS

An "Indirect Connector" is considered one which pairs with an Adapter which in turn talks to the system of record or service layer.

i.e. API -> Connector -> Adapter -> CBS

The advantage of a Direct connector is that its perhaps simpler. The disadvantage is that you have to code in a JVM language, understand a bit about OBP internals and a bit of Scala.

The advantage of the Indirect Connector is that you can write the Adapter in any language and the Connector and Adapter are decoupled (you just have to respect the Outbound / Inbound message format).

The default Connector in OBP is a Direct Connector called "mapped". It is called the "mapped" connector because it talks directly to the OBP database (Postgres, MySQL, Oracle, MSSQL etc.) via the Liftweb ORM which is called Mapper.

If you want to create your own (Direct) Connector you can fork any of the connectors within OBP.

There is a special Connector called the Star Connector which can use functions from all the normal connectors.

Using the Star Connector we can dynamically reroute function calls to different Connectors per function per bank_id.

The OBP API Manager has a GUI to manage this or you can use the OBP Method Routing APIs to set destinations for each function call.

Note: We generate the source code for individual connectors automatically.

Connector Method

Developers can override all the existing Connector methods.
This function needs to be used together with the Method Routing.
When we set "connector = internal", then the developer can call their own method body at API level.

For example, the GetBanks endpoint calls the connector "getBanks" method. Then, developers can use these endpoints to modify the business logic in the getBanks method body.

The following videos are available:
* Introduction for Connector Method
* Introduction 2 for Connector Method

Go Back to Connector Method APIs

ConnectorMethod.connectorMethodId

Example value: ace0352a-9a0f-4bfa-b30b-9003aa467f51

Description: A string that MUST uniquely identify the connector method on this OBP instance, can be used in all cache.

Consents provide a mechanism by which a third party App or User can access resources on behalf of a User.

Consent OBP Flow Example

1) Call endpoint Create Consent Request using application access (Client Credentials)

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/consumer/consent-requests

Post body:

{
  "everything": false,
  "account_access": [],
  "entitlements": [
    {
      "bank_id": "gh.29.uk.x",
      "role_name": "CanGetCustomer"
    }
  ],
  "email": "marko@tesobe.com"
}

Output:

{
  "consent_request_id":"bc0209bd-bdbe-4329-b953-d92d17d733f4",
  "payload":{
    "everything":false,
    "account_access":[],
    "entitlements":[{
      "bank_id":"gh.29.uk.x",
      "role_name":"CanGetCustomer"
    }],
    "email":"marko@tesobe.com"
  },
  "consumer_id":"0b34068b-cb22-489a-b1ee-9f49347b3346"
}

2) Call endpoint Create Consent By CONSENT_REQUEST_ID (SMS) with logged on user

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/consumer/consent-requests/bc0209bd-bdbe-4329-b953-d92d17d733f4/EMAIL/consents

Output:

{
  "consent_id":"155f86b2-247f-4702-a7b2-671f2c3303b6",
  "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-vE",
  "status":"INITIATED",
  "consent_request_id":"bc0209bd-bdbe-4329-b953-d92d17d733f4"
}

3) We receive the SCA message via SMS

Your consent challenge : 29131491, Application: Any application

4) Call endpoint Answer Consent Challenge with logged on user

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/banks/gh.29.uk.x/consents/155f86b2-247f-4702-a7b2-671f2c3303b6/challenge
Post body:

{
  "answer": "29131491"
}

Output:

{
  "consent_id":"155f86b2-247f-4702-a7b2-671f2c3303b6",
  "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-vE",
  "status":"ACCEPTED"
}

5) Call endpoint Get Customer by CUSTOMER_ID with Consent Header

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/banks/gh.29.uk.x/customers/a9c8bea0-4f03-4762-8f27-4b463bb50a93

Request Header:

Consent-JWT:eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-

Output:

{
  "bank_id":"gh.29.uk.x",
  "customer_id":"a9c8bea0-4f03-4762-8f27-4b463bb50a93",
  "customer_number":"0908977830011-#2",
  "legal_name":"NONE",
  "mobile_phone_number":"+3816319549071",
  "email":"marko@tesobe.com1",
  "face_image":{
    "url":"www.openbankproject",
    "date":"2017-09-18T22:00:00Z"
  },
  "date_of_birth":"2017-09-18T22:00:00Z",
  "relationship_status":"Single",
  "dependants":5,
  "dob_of_dependants":[],
  "credit_rating":{
    "rating":"3",
    "source":"OBP"
  },
  "credit_limit":{
    "currency":"EUR",
    "amount":"10001"
  },
  "highest_education_attained":"Bachelor’s Degree",
  "employment_status":"Employed",
  "kyc_status":true,
  "last_ok_date":"2017-09-18T22:00:00Z",
  "title":null,
  "branch_id":"3210",
  "name_suffix":null,
  "customer_attributes":[]
}


Consent / Account Onboarding

Consent, or Account onboarding, is the process by which the account owner gives permission for their account(s) to be accessible to the API endpoints.

In OBP, the account, transaction and payment APIs are all guarded by Account Views - with one exception, the account holders endpoint which can be used to
bootstrap account on-boarding.

Note: the account holders endpoint is generally made available only to the Account Onboarding App, so if a View does not exist, no API access to the account is possible.

Consent or Account onboarding can be managed in one of two ways:

1) A backend system (CBS or other) is the system of record for User Consent, and OBP mirrors this.

In this case:

a) OBP requires the CBS or other backend system to return a list of accounts and permissions associated with a User.

b) At User login, OBP automatically creates one or more Views for that User based on the permissions supplied by the CBS.

2) OBP is the system of record for User Consent.

In this case:

a) OBP requires the CBS, Gateway or other system to provide just a basic list of accounts owned by the User.

b) The Onboarding App or Bank's Onboarding Page then authenticates the User and calls the Create View endpoint.

c) The account, transaction and payment API endpoints then work as moderated by the relevant View permissions.

d) The User can revoke access by calling the delete View endpoint.

In summary:

Prior to Views being created on an Account for a User, only the 'accounts held' endpoint will work for the account holder, and this endpoint only provides enough information
to identify the account so it can be selected and on-boarded into the API.

Once a View exists for an Account, a User can interact with the Account via the API based on permissions defined in the View.


OBP Access Control Image

Go Back to Consent APIs

Consent, or Account onboarding, is the process by which the account owner gives permission for their account(s) to be accessible to the API endpoints.

In OBP, the account, transaction and payment APIs are all guarded by Account Views - with one exception, the account holders endpoint which can be used to
bootstrap account on-boarding.

Note: the account holders endpoint is generally made available only to the Account Onboarding App, so if a View does not exist, no API access to the account is possible.

Consent or Account onboarding can be managed in one of two ways:

1) A backend system (CBS or other) is the system of record for User Consent, and OBP mirrors this.

In this case:

a) OBP requires the CBS or other backend system to return a list of accounts and permissions associated with a User.

b) At User login, OBP automatically creates one or more Views for that User based on the permissions supplied by the CBS.

2) OBP is the system of record for User Consent.

In this case:

a) OBP requires the CBS, Gateway or other system to provide just a basic list of accounts owned by the User.

b) The Onboarding App or Bank's Onboarding Page then authenticates the User and calls the Create View endpoint.

c) The account, transaction and payment API endpoints then work as moderated by the relevant View permissions.

d) The User can revoke access by calling the delete View endpoint.

In summary:

Prior to Views being created on an Account for a User, only the 'accounts held' endpoint will work for the account holder, and this endpoint only provides enough information
to identify the account so it can be selected and on-boarded into the API.

Once a View exists for an Account, a User can interact with the Account via the API based on permissions defined in the View.

1) Call endpoint Create Consent Request using application access (Client Credentials)

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/consumer/consent-requests

Post body:

{
  "everything": false,
  "account_access": [],
  "entitlements": [
    {
      "bank_id": "gh.29.uk.x",
      "role_name": "CanGetCustomer"
    }
  ],
  "email": "marko@tesobe.com"
}

Output:

{
  "consent_request_id":"bc0209bd-bdbe-4329-b953-d92d17d733f4",
  "payload":{
    "everything":false,
    "account_access":[],
    "entitlements":[{
      "bank_id":"gh.29.uk.x",
      "role_name":"CanGetCustomer"
    }],
    "email":"marko@tesobe.com"
  },
  "consumer_id":"0b34068b-cb22-489a-b1ee-9f49347b3346"
}

2) Call endpoint Create Consent By CONSENT_REQUEST_ID (SMS) with logged on user

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/consumer/consent-requests/bc0209bd-bdbe-4329-b953-d92d17d733f4/EMAIL/consents

Output:

{
  "consent_id":"155f86b2-247f-4702-a7b2-671f2c3303b6",
  "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-vE",
  "status":"INITIATED",
  "consent_request_id":"bc0209bd-bdbe-4329-b953-d92d17d733f4"
}

3) We receive the SCA message via SMS

Your consent challenge : 29131491, Application: Any application

4) Call endpoint Answer Consent Challenge with logged on user

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/banks/gh.29.uk.x/consents/155f86b2-247f-4702-a7b2-671f2c3303b6/challenge
Post body:

{
  "answer": "29131491"
}

Output:

{
  "consent_id":"155f86b2-247f-4702-a7b2-671f2c3303b6",
  "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-vE",
  "status":"ACCEPTED"
}

5) Call endpoint Get Customer by CUSTOMER_ID with Consent Header

Url: https://obp-api-sandbox.nmbbank.co.tz/obp/v5.0.0/banks/gh.29.uk.x/customers/a9c8bea0-4f03-4762-8f27-4b463bb50a93

Request Header:

Consent-JWT:eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEN1c3RvbWVyIiwiYmFua19pZCI6ImdoLjI5LnVrLngifV0sImNyZWF0ZWRCeVVzZXJJZCI6ImFiNjUzOWE5LWIxMDUtNDQ4OS1hODgzLTBhZDhkNmM2MTY1NyIsInN1YiI6IjU3NGY4OGU5LTE5NDktNDQwNy05NTMwLTA0MzM3MTU5YzU2NiIsImF1ZCI6IjFhMTA0NjNiLTc4NTYtNDU4ZC1hZGI2LTViNTk1OGY1NmIxZiIsIm5iZiI6MTY2OTg5NDU5OSwiaXNzIjoiaHR0cDpcL1wvMTI3LjAuMC4xOjgwODAiLCJleHAiOjE2Njk4OTgxOTksImlhdCI6MTY2OTg5NDU5OSwianRpIjoiMTU1Zjg2YjItMjQ3Zi00NzAyLWE3YjItNjcxZjJjMzMwM2I2Iiwidmlld3MiOltdfQ.lLbn9BtgKvgAcb07if12SaEyPAKgXOEmr6x3Y5pU-

Output:

{
  "bank_id":"gh.29.uk.x",
  "customer_id":"a9c8bea0-4f03-4762-8f27-4b463bb50a93",
  "customer_number":"0908977830011-#2",
  "legal_name":"NONE",
  "mobile_phone_number":"+3816319549071",
  "email":"marko@tesobe.com1",
  "face_image":{
    "url":"www.openbankproject",
    "date":"2017-09-18T22:00:00Z"
  },
  "date_of_birth":"2017-09-18T22:00:00Z",
  "relationship_status":"Single",
  "dependants":5,
  "dob_of_dependants":[],
  "credit_rating":{
    "rating":"3",
    "source":"OBP"
  },
  "credit_limit":{
    "currency":"EUR",
    "amount":"10001"
  },
  "highest_education_attained":"Bachelor’s Degree",
  "employment_status":"Employed",
  "kyc_status":true,
  "last_ok_date":"2017-09-18T22:00:00Z",
  "title":null,
  "branch_id":"3210",
  "name_suffix":null,
  "customer_attributes":[]
}

Consumer

The "consumer" of the API, i.e. the web, mobile or serverside "App" that calls on the OBP API on behalf of the end user (or system).

Each Consumer has a consumer key and secrect which allows it to enter into secure communication with the API server.

Go Back to Consumer APIs

Consumer, Consent, Transport and Payload Security

Consumer, Consent, Transport and Payload Security with MTLS and JWS
This glossary item aims to give an overview of how the communication between an Application and the OBP API server is secured with Consents, Consumer records, MTLs and JWS.

It includes some implementation step notes for the Application developer.

The following components are required:

Consumer record

The Application must have an active API Consumer / Client record on the server.

MTLS

With Mutual TLS both the Consumer and the Server (OBP API) must use certificates.

JWS

The Request is signed by the Consumer with a JWS using the client certificate of the Consumer. Example: OBP-Hola private void requestIntercept
The Request is validated by the OBP API Server using the JWS provided by the Consumer. See OBP-API def verifySignedRequest
The Response is signed by the OBP API Server with a JWS. See OBP-API def signResponse
The Response is validated by the Client using the JWS provided by the OBP API Server. Example: OBP-Hola private void responseIntercept

Consent

The end user must give permission to the Application in order for the Application to see his/her account and transaction data.

obp-permission-transport-and-payload-security

In order to get an App / Consumer key

Sign up or login as a developer.

Register your App / Consumer HERE

Be sure to enter your Client Certificate in the above form. To create the user.crt file see HERE

Authenticate

To test the service your App will need to authenticate using OAuth2.

You can use the OBP Hola App as an example / starting point for your App.

Counterparty.counterpartyId

Example value: 9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: The Counterparty ID used in URLs. This SHOULD NOT be a name of a Counterparty.

Counterparty.counterpartyName

Example value: John Smith Ltd.

Description: The name of a Counterparty. Ideally unique for an Account

Counterparty.isBeneficiary

Example value: true

Description: This is a boolean. True if the originAccount can send money to the Counterparty

Customer

The legal entity that has the relationship to the bank. Customers are linked to Users via User Customer Links. Customer attributes include Date of Birth, Customer Number etc.

Go Back to Customer APIs

Customer.Credit.rating

Example value:

Description: .

Customer.Credit.source

Example value:

Description: .

Customer.attributeAlias

Example value: STRING

Description: Customer attribute alias.

Customer.attributeId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: Customer attribute id

Customer.attributeId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: User attribute id

Customer.attributeName

Example value: SPECIAL_TAX_NUMBER

Description: Customer attribute name

Customer.attributeType

Example value: STRING

Description: Customer attribute type.

Customer.attributeValue

Example value: 123456789

Description: Customer attribute value.

Customer.consumerId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A non human friendly string that identifies the consumer. It is the app which calls the apis

Customer.customerAccountLinkId

Example value: xyz8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A non human friendly string that identifies the Customer Account Link and is used in URLs.

Customer.customerAttributeId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A non human friendly string that identifies the customer attribute and is used in URLs.

Customer.customerAttributeName

Example value: SPECIAL_TAX_NUMBER

Description: The Customer Attribute name, eg: SPECIAL_TAX_NUMBER

Customer.customerAttributeType

Example value: STRING

Description: It can be STRING, INTEGER, DOUBLE, DATE_WITH_DAY

Customer.customerAttributeValue

Example value: 123456789

Description: The Customer Attribute value of the current attribute type, eg: 123456789.

Customer.customerId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A non human friendly string that identifies the customer and is used in URLs. This SHOULD NOT be the customer number. The combination of customerId and bankId MUST be unique on an OBP instance. customerId SHOULD be unique on an OBP instance. Ideally customerId is a UUID. A mapping between customer number and customer id is kept in OBP.

Customer.customerNumber

Example value: 5987953

Description: The human friendly customer identifier that MUST uniquely identify the Customer at the Bank ID. Customer Number is NOT used in URLs.

Customer.customer_id

The identifier that MUST NOT leak the customer number or other identifier nomrally used by the customer or bank staff. It SHOULD be a UUID and MUST be unique in combination with BANK_ID.

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Customer.dependants

Example value: 1

Description: the number of dependants

Customer.dependents

Example value: 2

Description: the number of dependents

Customer.employmentStatus

Example value: worker

Description: employment status

Customer.highestEducationAttained

Example value: Master

Description: highest education attained

Customer.key

Example value: bwf0ykmwoirip1yjxcn15wnhuyxcziwgtcoaildq

Description: This key should be used with Adapter.value together. They are a pair.

Customer.kycStatus

Example value: true

Description: This is boolean to indicate if the cusomter's KYC has been checked.

Customer.legalName

Example value: Eveline Tripman

Description: The legal name of the Customer.

Customer.mobileNumber

Example value: +44 07972 444 876

Description: The mobile number name of the Customer.

Customer.nameSuffix

Example value: Sr

Description: suffix of the name

Customer.relationshipStatus

Example value: single

Description: relationship status

Customer.relationshipType

Example value: Owner

Description: Relationship between two parties.

Customer.secret

Example value: xwdgylv3vau0n2gkxu1aize4glapftfldp5y1bic

Description: This key should be used with Adapter.value together. They are a pair.

Customer.title

Example value: Dr.

Description: title of the name

DAuth

DAuth Introduction, Setup and Usage

DAuth is an experimental authentication mechanism that aims to pin an ethereum or other blockchain Smart Contract to an OBP "User".

In the future, it might be possible to be more specific and pin specific actors (wallets) that are acting within the smart contract, but so far, one smart contract acts on behalf of one User.

Thus, if a smart contract "X" calls the OBP API using the DAuth header, OBP will get or create a user called X and the call will proceed in the context of that User "X".

DAuth is invoked by the REST client (caller) including a specific header (see step 3 below) in any OBP REST call.

When OBP receives the DAuth token, it creates or gets a User with a username based on the smart_contract_address and the provider based on the network_name. The combination of username and provider is unique in OBP.

If you are calling OBP-API via an API3 Airnode, the Airnode will take care of constructing the required header.

When OBP detects a DAuth header / token it first checks if the Consumer is allowed to make such a call. OBP will validate the Consumer ip address and signature etc.

Note: The DAuth flow does not require an explicit POST like Direct Login to create the token.

Permissions may be assigned to an OBP User at any time, via the UserAuthContext, Views, Entitlements to Roles or Consents.

Note: DAuth is NOT enabled on this instance!

Note: The DAuth client is responsible for creating a token which will be trusted by OBP absolutely!

To use DAuth:

1) Configure OBP API to accept DAuth.

Set up properties in your props file

# -- DAuth --------------------------------------
# Define secret used to validate JWT token
# jwt.public_key_rsa=path-to-the-pem-file
# Enable/Disable DAuth communication at all
# In case isn't defined default value is false
# allow_dauth=false
# Define comma separated list of allowed IP addresses
# dauth.host=127.0.0.1
# -------------------------------------- DAuth--

Please keep in mind that property jwt.public_key_rsa is used to validate JWT token to check it is not changed or corrupted during transport.

2) Create / have access to a JWT

The following videos are available:
* DAuth in local environment

HEADER:ALGORITHM & TOKEN TYPE

{
  "alg": "RS256",
  "typ": "JWT"
}

PAYLOAD:DATA

{
  "smart_contract_address": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
  "network_name": "AIRNODE.TESTNET.ETHEREUM",
  "msg_sender": "0xe12340927f1725E7734CE288F8367e1Bb143E90fhku767",
  "consumer_key": "0x1234a4ec31e89cea54d1f125db7536e874ab4a96b4d4f6438668b6bb10a6adb",
  "timestamp": "2021-11-04T14:13:40Z",
  "request_id": "0Xe876987694328763492876348928736497869273649"
}

VERIFY SIGNATURE

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

) your-RSA-key-pair

Here is an example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k

3) Try a REST call using the header

Using your favorite http client:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current

Body

Leave Empty!

Headers:

   DAuth: your-jwt-from-step-above

Here is it all together:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current HTTP/1.1
Host: localhost:8080
User-Agent: curl/7.47.0
Accept: /
DAuth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k

CURL example

curl -v -H 'DAuth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFydF9jb250cmFjdF9hZGRyZXNzIjoiMHhlMTIzNDI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGJiM0YwNTEyMjQiLCJuZXR3b3JrX25hbWUiOiJFVEhFUkVVTSIsIm1zZ19zZW5kZXIiOiIweGUxMjM0MDkyN2YxNzI1RTc3MzRDRTI4OEY4MzY3ZTFCYjE0M0U5MGZoa3U3NjciLCJjb25zdW1lcl9rZXkiOiIweDEyMzRhNGVjMzFlODljZWE1NGQxZjEyNWRiNzUzNmU4NzRhYjRhOTZiNGQ0ZjY0Mzg2NjhiNmJiMTBhNmFkYiIsInRpbWVzdGFtcCI6IjIwMjEtMTEtMDRUMTQ6MTM6NDBaIiwicmVxdWVzdF9pZCI6IjBYZTg3Njk4NzY5NDMyODc2MzQ5Mjg3NjM0ODkyODczNjQ5Nzg2OTI3MzY0OSJ9.XSiQxjEVyCouf7zT8MubEKsbOBZuReGVhnt9uck6z6k' https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current

You should receive a response like:

{
    "user_id": "4c4d3175-1e5c-4cfd-9b08-dcdc209d8221",
    "email": "",
    "provider_id": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
    "provider": "ETHEREUM",
    "username": "0xe123425E7734CE288F8367e1Bb143E90bb3F051224",
    "entitlements": {
        "list": []
    }
}

Under the hood

The file, dauth.scala handles the DAuth,

We:

-> Check if Props allow_dauth is true
  -> Check if DAuth header exists
    -> Check if getRemoteIpAddress is OK
      -> Look for "token"
        -> parse the JWT token and getOrCreate the user
          -> get the data of the user

More information

Parameter names and values are case sensitive.
Each parameter MUST NOT appear more than once per request.

Data Model Overview

An overview of the Open Bank Project Data Model.

This diagram may help in understanding the Open Bank Project entities, capabilities and concepts. However, it is subject to change. If we change the data model, we release migration scripts.

obp-data-model-overview

Direct Login

Direct Login is a simple authentication process to be used at hackathons and trusted environments:

1) Get your App key

Sign up or login as a developer.

Register your App key HERE

Copy and paste the consumer key for step two below.

2) Authenticate

Using your favorite http client:

POST https://obp-api-sandbox.nmbbank.co.tz/my/logins/direct

Body

Leave Empty!

Headers:

Content-Type:  application/json


directlogin: username=janeburel,
             password=the-password-of-jane,
             consumer_key=your-consumer-key-from-step-one

Here is it all together:

POST https://obp-api-sandbox.nmbbank.co.tz/my/logins/direct HTTP/1.1
directlogin: username=janeburel, password=686876, consumer_key=GET-YOUR-OWN-API-KEY-FROM-THE-OBP
Content-Type: application/json
Host: 127.0.0.1:8080
Connection: close
User-Agent: Paw/2.3.3 (Macintosh; OS X/10.11.3) GCDHTTPRequest
Content-Length: 0

Note: HTTP/2.0 requires that header names are lower case. Currently the header name for directlogin is case insensitive.

To troubleshoot request headers, you may want to ask your administrator to Echo Request headers.

You should receive a token:

{"token":"a-long-token-string"}

3) Make authenticated API calls

In subsequent calls you can use the token received in step 2

e.g.

Action:

PUT https://obp-api-sandbox.nmbbank.co.tz/obp/v2.0.0/banks/obp-bankx-n/accounts/my-new-account-id

Body:

{  "type":"CURRENT",  "balance":{    "currency":"USD",    "amount":"0"  }}

Headers:

Content-Type:  application/json

directlogin: token=your-token-from-step-2

Here is another example:

PUT https://obp-api-sandbox.nmbbank.co.tz/obp/v2.0.0/banks/enbd-egy--p3/accounts/newaccount1 HTTP/1.1
directlogin: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyIiOiIifQ.C8hJZNPDI59OOu78pYs4BWp0YY_21C6r4A9VbgfZLMA
Content-Type: application/json
Cookie: JSESSIONID=7h1ssu6d7j151u08p37a6tsx1
Host: 127.0.0.1:8080
Connection: close
User-Agent: Paw/2.3.3 (Macintosh; OS X/10.11.3) GCDHTTPRequest
Content-Length: 60

{"type":"CURRENT","balance":{"currency":"USD","amount":"0"}}

More information

Parameter names and values are case sensitive.
The following parameters must be sent by the client to the server:

   username
     The name of the user to authenticate.

   password
     The password used to authenticate user. Alphanumeric string.

   consumer_key
     The application identifier. Generated on OBP side via
     https://obp-api-sandbox.nmbbank.co.tz/consumer-registration endpoint.

Each parameter MUST NOT appear more than once per request.

Dummy Customer Logins

The following dummy Customer Logins may be used by developers testing their applications on this sandbox:

Login / Password / Email address

Robert.Uk.01 X!34e31b62 robert.uk.01@x.y
Susan.Uk.01 X!c4d9ddf5 susan.uk.01@x.y
Anil.Uk.01 X!fb072b9e anil.uk.01@x.y
Ellie.Uk.01 X!592a89fc ellie.uk.01@x.y
Rosalie.Uk.01 X!007bf69f rosalie.uk.01@x.y
Chris.Uk.01 X!615470c9 chris.uk.01@x.y
Dennis.Uk.01 X!a78282e3 dennis.uk.01@x.y
Jane.Uk.01 X!fadb5f54 jane.uk.01@x.y
Emma.Uk.01 X!23e7c122 emma.uk.01@x.y
Sebastien.Uk.01 X!3146312a sebastien.uk.01@x.y
Wim.Uk.01 X!6345735b wim.uk.01@x.y
Simon.Uk.01 X!2f3079b6 simon.uk.01@x.y
Jean-paul.Uk.01 X!0536a495 jean-paul.uk.01@x.y
Elise.Uk.01 X!3471e6eb elise.uk.01@x.y
Eleanor.Uk.01 X!fc2fb09a eleanor.uk.01@x.y
Robert.Nmbb.01 X!317fa36e robert.nmbb.01@x.y
Susan.Nmbb.01 X!19fbbe5c susan.nmbb.01@x.y
Anil.Nmbb.01 X!0133bddd anil.nmbb.01@x.y
Ellie.Nmbb.01 X!0a745cc6 ellie.nmbb.01@x.y
Rosalie.Nmbb.01 X!313002ef rosalie.nmbb.01@x.y
Chris.Nmbb.01 X!b73475de chris.nmbb.01@x.y
Dennis.Nmbb.01 X!cc69f4a1 dennis.nmbb.01@x.y
Jane.Nmbb.01 X!bca085b1 jane.nmbb.01@x.y
Emma.Nmbb.01 X!c2fe4c0a emma.nmbb.01@x.y
Sebastien.Nmbb.01 X!5bf3fb2c sebastien.nmbb.01@x.y
Wim.Nmbb.01 X!78b757b4 wim.nmbb.01@x.y
Simon.Nmbb.01 X!c187a4bd simon.nmbb.01@x.y
Jean-paul.Nmbb.01 X!f58ddece jean-paul.nmbb.01@x.y
Elise.Nmbb.01 X!7f525d1b elise.nmbb.01@x.y
Eleanor.Nmbb.01 X!c7d23f46 eleanor.nmbb.01@x.y

https://obp-apiexplorer-sandbox.nmbbank.co.tz/glossary#customer-logins

Dynamic Endpoint Manage

If you want to create endpoints from Swagger / Open API specification files, use Dynamic Endpoints.

We use the term "Dynamic" because these Endpoints persist in the OBP database and are served from real time generated Scala code.

This contrasts to the "Static" endpoints (see the Static glossary item) which are served from static Scala code.

Dynamic endpoints can be changed in real-time and do not require an OBP instance restart.

When you POST a swagger file, all the endpoints defined in the swagger file, will be created in this OBP instance.

You can create a set of endpoints in three different modes:

1) If the host field in the Swagger file is set to "dynamic_entity", then you should link the swagger JSON fields to Dynamic Entity fields. To do this use the Endpoint Mapping endpoints.

2) If the host field in the Swagger file is set to "obp_mock", the Dynamic Endpoints created will return example responses defined in the swagger file.

3) If you need to link the responses to external resource, use the Method Routing endpoints.

Dynamic Endpoints can be created at the System level (bank_id is null) or Bank / Space level (bank_id is NOT null).
You might want to create Bank level Dynamic Entities in order to grant automated roles based on user email domain. See the OBP-API sample.props.template

Upon the successful creation of each Dynamic Endpoint, OBP will automatically:

*Create a Guard with a named Role on the Endpoint to protect it from unauthorised users.
*Grant you an Entitlement to the required Role so you can call the endpoint and pass its Guard.

The following videos are available:

Go Back to Dynamic Endpoint Manage APIs

Dynamic Entity Manage

Dynamic Entities can be used to store and retrieve custom data objects (think your own tables and fields) in the OBP instance.

You can define your own Dynamic Entities or use Dynamic Entities created by others.

You would use Dynamic Entities if you want to go beyond the OBP standard data model and store custom data structures. Note, if you want to extend the core OBP banking model of Customers, Products, Accounts, Transactions and so on you can also add Custom Attributes to these standard objects.

You would use Dynamic Endpoints if you want to go beyond the standard OBP or other open banking standard APIs.

Dynamic Entities have their own REST APIs so you can easily Create, Read, Update and Delete records. However, you can also connect Dynamic Endpoints with your own API definitions (via Swagger) and so create custom GET endpoints connecting to any combination of Dynamic Entities.

Dynamic Endpoints can retrieve the data of Dynamic Entities so you can effectively create bespoke endpoint / data combinations - at least for GET endpoints - using Dynamic Endpoints, Entities and Endpoint Mapping.

In order to use Dynamic Entities you will need to have the appropriate Entitlements to Create, Read, Update or Delete records in the Dynamic Entity.

You define your Dynamic Entities in JSON.

Fields are typed, have an example value and a (markdown) description. They can also be constrained in size.

You can also create field "references" to other fields in other Entities. These are like foreign keys to other Dynamic or Static (built in) entities.
In other words, if you create an Entity called X which has a field called A, you can force the values of X.A to match the values of Y.B where Y is another Dynamic Entity or Z.B where Z is a Static (OBP) Entity.
If you want to add data to an existing Entity, you can create a Dynamic Entity which has a reference field to the existing entity.

Dynamic Entities can be created at the System level (bank_id is null) - or Bank / Space level (bank_id is not null). You might want to create Bank level Dynamic Entities in order to grant automated roles based on user email domain.

When creating a Dynamic Entity, OBP automatically:

  • Creates a data structure in the OBP database in which to store the records of the new Entity.
  • Creates a primary key for the Entity which can be used to update and delete the Entity.
  • Creates Create, Read, Update and Delete endpoints to operate on the Entity so you can insert, get, modify and delete records. These CRUD operations are all available over the generated REST endpoints.
  • Creates Roles to guard the above endpoints.

Following the creation of a Dynamic Entity you will need to grant yourself or others the appropriate roles before you can insert or get records.

The generated Roles required for CRUD operations on a Dynamic Entity are like any other OBP Role i.e. they can be requested, granted, revoked and auto-granted using the API Explorer / API Manager or via REST API. To see the Roles required for a Dynamic Entities endpoints, see the API Explorer for each endpoint concerned.

Each Dynamic Entity gets a dynamicEntityId which uniquely identifies it and also the userId which identifies the user who created the Entity. The dynamicEntityId is used to update the definition of the Entity.

To visualise any data contained in Dynamic Entities you could use external BI tools and use the GET endpoints and authenticate using OAuth or Direct Login.

The following videos are available:

Go Back to Dynamic Entity Manage APIs

Dynamic Message Doc

In OBP we represent messages sent by a Connector method / function as MessageDocs.
A MessageDoc defines the message the Connector sends to an Adapter and the response it expects from the Adapter.

Using this endpoint, developers can create their own scala methods aka Connectors in OBP code.
These endpoints are designed for extending the current connector methods.

When you call the Dynamic Resource Doc endpoints, sometimes you need to call internal Scala methods which
don't yet exist in the OBP code. In this case you can use these endpoints to create your own internal Scala methods.

You can also use these endpoints to create your own helper methods in OBP code.

This feature is somewhat work in progress (WIP).

The following videos are available:
* Introduction to Dynamic Message Doc

Go Back to Dynamic Message Doc APIs

DynamicConnectorMethod.lang

Example value: Scala

Description: the programming language of OBP connector method body.

DynamicConnectorMethod.methodBody.Java

Example value: package%20code.bankconnectors%3B%0A%0Aimport%20com.openbankproject.commons.model.%3B%0Aimport%20java.util.function.Function%3B%0Aimport%20java.util.function.Supplier%3B%0A%0A%2F**%0A%20%20This%20is%20a%20java%20dynamic%20function%20template.%0A%20*%20Must%20copy%20the%20whole%20content%20of%20the%20file%20as%20%22dynamic%20method%20body%22.%0A%20*%20Currently%2C%20support%20Java%201.8%20version%20language%20features%0A%20*%2F%0Apublic%20class%20DynamicJavaConnector%20implements%20Supplier%3CFunction%3CObject%5B%5D%2C%20Object%3E%3E%20%7B%0A%20%20%20%20private%20Object%20apply(Object%5B%5D%20args)%20%7B%0A%20%20%20%20%20%20%20BankId%20bankId%20%3D%20(BankId)%20args%5B0%5D%3B%0A%0A%20%20%20%20%20%20%20Bank%20bank%20%3D%20new%20BankCommons(bankId%2C%20%22The%20Java%20Bank%20of%20Scotland%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22The%20Royal%20Bank%20of%20Scotland%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22http%3A%2F%2Fwww.red-bank-shoreditch.com%2Flogo.gif%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22http%3A%2F%2Fwww.red-bank-shoreditch.com%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22OBP%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22Java%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22Swift%20bic%20value%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22Java%22%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20)%3B%0A%20%20%20%20%20%20%20return%20bank%3B%0A%20%20%20%20%7D%0A%0A%20%20%20%20%40Override%0A%20%20%20%20public%20Function%3CObject%5B%5D%2C%20Object%3E%20get()%20%7B%0A%20%20%20%20%20%20%20%20return%20this%3A%3Aapply%3B%0A%20%20%20%20%7D%0A%7D%0A

Description: the URL-encoded format String, the original Java code is the OBP connector method body.

DynamicConnectorMethod.methodBody.Js

Example value: %7B%0A%20%20%20%20const%20%5BbankId%5D%20%3D%20args%3B%0A%20%20%20%20%2F%2F%20call%20java%20or%20scala%20type%20in%20this%20way%0A%20%20%20%20const%20BigDecimal%20%3D%20Java.type(%27java.math.BigDecimal%27)%3B%0A%20%20%20%20%2F%2F%20define%20a%20class%0A%20%20%20%20class%20SwiftBic%7B%0A%20%20%20%20%20%20%20%20constructor(name%2C%20value)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20this.name%20%3D%20name%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20this.value%20%3D%20value%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20%2F%2F%20define%20async%20function%0A%20%20%20%20const%20someAsyncFn%20%3D%20async%20()%20%3D%3E%20new%20BigDecimal(%27123.456%27)%0A%20%20%20%20%2F%2F%20call%20other%20async%20methods%0A%20%20%20%20const%20data%20%3D%20await%20someAsyncFn()%3B%0A%0A%20%20%20%20const%20bank%20%3D%20%7B%0A%20%20%20%20%20%20%20%20%22bankId%22%3A%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%3A%22HelloJsBank%3A%22%2B%20bankId%0A%20%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%20%22shortName%22%3A%22The%20Js%20Bank%20of%20Scotland%22%20%2Bdata.toString()%2C%0A%20%20%20%20%20%20%20%20%22fullName%22%3A%22The%20Js%20Bank%20of%20Scotland%22%2C%0A%20%20%20%20%20%20%20%20%22logoUrl%22%3A%22http%3A%2F%2Fwww.red-bank-shoreditch.com%2Flogo.gif%22%2C%0A%20%20%20%20%20%20%20%20%22websiteUrl%22%3A%22http%3A%2F%2Fwww.red-bank-shoreditch.com%22%2C%0A%20%20%20%20%20%20%20%20%22bankRoutingScheme%22%3A%22OBP%22%2C%0A%20%20%20%20%20%20%20%20%22bankRoutingAddress%22%3A%22Js%22%2C%0A%20%20%20%20%20%20%20%20%22swiftBic%22%3A%20new%20SwiftBic(%22Mock%20Swift%22%2C%2010).name%2C%0A%20%20%20%20%20%20%20%20%22nationalIdentifier%22%3A%22Js%22%2C%0A%20%20%20%20%7D%0A%0A%20%20%20%20return%20bank%3B%0A%7D

Description: the URL-encoded format String, the original Js code is the OBP connector method body.

DynamicConnectorMethod.methodBody.scala

Example value: %20%20%20%20%20%20Future.successful%28%0A%20%20%20%20%20%20%20%20Full%28%28BankCommons%28%0A%20%20%20%20%20%20%20%20%20%20BankId%28%22Hello%20bank%20id%22%29%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%228%22%0A%20%20%20%20%20%20%20%20%29%2C%20None%29%29%0A%20%20%20%20%20%20%29

Description: the URL-encoded format String, the original code is the OBP connector method body.

DynamicMessageDoc.dynamicMessageDocId

Example value:

Description: no-description-provided

DynamicMessageDoc.inboundAvroSchema

Example value:

Description: no-description-provided

DynamicMessageDoc.outboundAvroSchema

Example value:

Description: no-description-provided

DynamicResourceDoc.description

Example value: Create one User

Description: the description for this endpoint

DynamicResourceDoc.dynamicResourceDocId

Example value: vce035ca-9a0f-4bfa-b30b-9003aa467f51

Description: A string that MUST uniquely identify the dynamic Resource Doc on this OBP instance, can be used in all cache.

DynamicResourceDoc.errorResponseBodies

Example value: OBP-50000: Unknown Error.,OBP-20001: User not logged in. Authentication is required!,OBP-20006: User is missing one or more roles: ,OBP-10001: Incorrect json format.

Description: The possible error messages of the endpoint.

DynamicResourceDoc.exampleRequestBody

Example value: {"name": "Jhon", "age": 12, "hobby": ["coding"],"optional_fields": ["hobby"]}

Description: the json string of the request body.

DynamicResourceDoc.implementedInApiVersion

Example value:

Description: no-description-provided

DynamicResourceDoc.isFeatured

Example value: false

Description: if this is featured or not

DynamicResourceDoc.methodBody

Example value: %20%20%20%20val%20Some(resourceDoc)%20%3D%20callContext.resourceDocument%0A%20%20%20%20val%20hasRequestBody%20%3D%20request.body.isDefined%0A%0A%20%20%20%20%2F%2F%20get%20Path%20Parameters%2C%20example%3A%0A%20%20%20%20%2F%2F%20if%20the%20requestUrl%20of%20resourceDoc%20is%20%2Fhello%2Fbanks%2FBANK_ID%2Fworld%0A%20%20%20%20%2F%2F%20the%20request%20path%20is%20%2Fhello%2Fbanks%2Fbank_x%2Fworld%0A%20%20%20%20%2F%2FpathParams.get(%22BANK_ID%22)%20will%20get%20Option(%22bank_x%22)%20value%0A%0A%20%20%20%20val%20myUserId%20%3D%20pathParams(%22MY_USER_ID%22)%0A%0A%0A%20%20%20%20val%20requestEntity%20%3D%20request.json%20match%20%7B%0A%20%20%20%20%20%20case%20Full(zson)%20%3D%3E%0A%20%20%20%20%20%20%20%20try%20%7B%0A%20%20%20%20%20%20%20%20%20%20zson.extract%5BRequestRootJsonClass%5D%0A%20%20%20%20%20%20%20%20%7D%20catch%20%7B%0A%20%20%20%20%20%20%20%20%20%20case%20e%3A%20MappingException%20%3D%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20Full(errorJsonResponse(s%22%24InvalidJsonFormat%20%24%7Be.msg%7D%22))%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20case%20_%3A%20EmptyBox%20%3D%3E%0A%20%20%20%20%20%20%20%20return%20Full(errorJsonResponse(s%22%24InvalidRequestPayload%20Current%20request%20has%20no%20payload%22))%0A%20%20%20%20%7D%0A%0A%0A%20%20%20%20%2F%2F%20please%20add%20business%20logic%20here%0A%20%20%20%20val%20responseBody%3AResponseRootJsonClass%20%3D%20ResponseRootJsonClass(s%22%24%7BmyUserId%7D_from_path%22%2C%20requestEntity.name%2C%20requestEntity.age%2C%20requestEntity.hobby)%0A%20%20%20%20Future.successful%20%7B%0A%20%20%20%20%20%20(responseBody%2C%20HttpCode.%60200%60(callContext.callContext))%0A%20%20%20%20%7D

Description: the URL-encoded format String, the original code is the OBP connector method body.

DynamicResourceDoc.partialFunction

Example value:

Description: no-description-provided

DynamicResourceDoc.partialFunctionName

Example value: getBanks

Description: partial function name

DynamicResourceDoc.partialFunctionName

Example value: createUser

Description: partial function name

DynamicResourceDoc.requestUrl

Example value: /my_user/MY_USER_ID

Description: The URL of the endpoint.

DynamicResourceDoc.requestVerb

Example value: POST

Description: This is the HTTP methods, eg: GET, POST, PUT, DELETE

DynamicResourceDoc.specialInstructions

Example value:

Description: no-description-provided

DynamicResourceDoc.specifiedUrl

Example value:

Description: no-description-provided

DynamicResourceDoc.successResponseBody

Example value: {"my_user_id": "some_id_value", "name": "Jhon", "age": 12, "hobby": ["coding"],"optional_fields": ["hobby"]}

Description: the json string of the success response body.

DynamicResourceDoc.summary

Example value: Create My User

Description: The summary of this endpoint

Echo Request Headers

Question: How can I see the request headers that OBP API finally receives from a REST client after the request has passed through HTTP infrastructure such as load balancers, firewalls and proxies?

Answer: If your OBP administrator (you?) sets the following OBP API Props:

echo_request_headers=true

then OBP API will echo all the request headers it receives to the response headers except that every request header name is prefixed with echo_

e.g. if you send the request header:value "DirectLogin:hello" it will be echoed in the response headers as "echo_DirectLogin:hello"

Note: HTTP/2.0 requires that header names must be lower case. This can be a source of confusion as some libraries / tools may drop or convert header names to lowercase.

Endpoint

The terms Endpoint and API (Application Programming Interface) are used somewhat interchangeably. However, an Endpoint is a specific URL defined by its path (eg. /obp/v4.0/root) and its http verb (e.g. GET, POST, PUT, DELETE etc).
Endpoints are like arrows into a system. Like any good computer function, endpoints should expect much and offer little in return. They should fail early and be clear about any reason for failure. In other words each endpoint should have a tight and limited contract with any caller - and especially the outside world!

In OBP, all system endpoints are RESTful - and most Open Banking Standards are RESTful. However, it is possible to create non-RESTful APIs in OBP using the Create Endpoint endpoints.

You can immediately tell if an endpoint is not RESTful by seeing a verb in the URL. For example:

POST /customers is RESTful = GOOD
POST /create-customer is NOT RESTful (due to the word "create") = BAD

RESTful APIs use resource names in URL paths. You can think of RESTful resources like database tables. You wouldn't name a database table "create-customer", so don't use that in a URL path.

If we consider interacting with a Customers table, we read the data using GET /Customers and write to the table using POST /Customers. This model keeps the names clear and predictable.
Note that we are only talking about the front end interface here - anything could be happening in the backend - and that is one of the beauties of APIs. For instance GET /Customers could call 5 different databases and 3 XML services in the background. Similarly POST /Customers could insert into various different tables and backend services. The important thing is that the user of the API (The Consumer or Client in OAuth parlance) has a simple and consistent experience.

In OBP, all Endpoints are implemented by Partial Functions. A Partial Function is a function which only accepts (and responds) to calls with certain parameter values. In the case of API Endpoints the inputs to the Partial Functions are the URL path and http verb. Note that it would be possible to have different Partial Functions respond even to different query parameters, but for OBP static endpoints at least, we take the approach of URL path + http Verb is handled by one Partial Function.
Each Partial Function is identified by an Operation ID which uniquely identifies the endpoint in the system. Having an Operation ID allows us to decorate the Endpoint with metadata (e.g. Tags) and surround the Endpoint with behaviour such as JSON Schema Validation.

See also API

Endpoint Mapping

Endpoint Mapping can be used to map each JSON field in a Dynamic Endpoint to different Dynamic Entity fields.

This document assumes you already have some knowledge of OBP Dynamic Endpoints and Dynamic Entities.

To enable Endpoint Mapping for your Dynamic Endpoints, either set the host in the swagger file to "dynamic_entity" upon creation of the Dynamic Endpoints - or update the host using the Update Dynamic Endpoint Host endpoints.

Once the host is thus set, you can use the Endpoint Mapping endpoints to map the Dynamic Endpoint fields to Dynamic Entity data.

See the Create Endpoint Mapping JSON body. You will need to know the operation_id in advance and you can prepare the request_mapping and response_mapping objects. You can get the operation ID from the API Explorer or Get Dynamic Endpoints endpoints.

For more details and a walk through, please see the following video:

Go Back to Endpoint Mapping APIs

EndpointTag.endpointTagId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: A string that MUST uniquely identify the endpointTag on this OBP instance, can be used in all cache.

EndpointTag.tagName

Example value: BankAccountTag1

Description: The endpoint tag name

Gateway Login

Introduction

Note: Gateway Login is NOT enabled on this instance!

Gateway Login Authorisation is made by including a specific header (see step 3 below) in any OBP REST call.

Note: Gateway Login does not require an explicit POST like Direct Login to create the token.

The Gateway is responsible for creating a token which is trusted by OBP absolutely!

When OBP recieves a token via Gateway Login, OBP creates or gets a user based on the username supplied.

obp login via gateway and jwt

To use Gateway Login:

1) Configure OBP API to accept Gateway Login.

Set up properties in a props file

# -- Gateway login --------------------------------------
# Enable/Disable Gateway communication at all
# In case isn't defined default value is false
# allow_gateway_login=false
# Define comma separated list of allowed IP addresses
# gateway.host=127.0.0.1
# Define secret used to validate JWT token
# jwt.token_secret=your-at-least-256-bit-secret-token
# -------------------------------------- Gateway login --

Please keep in mind that property jwt.token_secret is used to validate JWT token to check it is not changed or corrupted during transport.

2) Create / have access to a JWT

HEADER:ALGORITHM & TOKEN TYPE

{
  "alg": "HS256",
  "typ": "JWT"
}

PAYLOAD:DATA

{
    "login_user_name": "username",
    "is_first": false,
    "app_id": "85a965f0-0d55-4e0a-8b1c-649c4b01c4fb",
    "app_name": "GWL",
    "time_stamp": "2018-08-20T14:13:40Z",
    "cbs_token": "your_token",
    "cbs_id": "your_cbs_id",
    "session_id": "123456789"
}

VERIFY SIGNATURE

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

) your-at-least-256-bit-secret-token

Here is the above example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJsb2dpbl91c2VyX25hbWUiOiJ1c2VybmFtZSIsImlzX2ZpcnN0IjpmYWxzZSwiYXBwX2lkIjoiODVhOTY1ZjAtMGQ1NS00ZTBhLThiMWMtNjQ5YzRiMDFjNGZiIiwiYXBwX25hbWUiOiJHV0wiLCJ0aW1lX3N0YW1wIjoiMjAxOC0wOC0yMFQxNDoxMzo0MFoiLCJjYnNfdG9rZW4iOiJ5b3VyX3Rva2VuIiwiY2JzX2lkIjoieW91cl9jYnNfaWQiLCJzZXNzaW9uX2lkIjoiMTIzNDU2Nzg5In0.
bfWGWttEEcftiqrb71mE6Xy1tT_I-gmDPgjzvn6kC_k

3) Try a REST call using the header

Using your favorite http client:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current

Body

Leave Empty!

Headers:

   Authorization: GatewayLogin token="your-jwt-from-step-above"

Here is it all together:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current HTTP/1.1
Host: localhost:8080
User-Agent: curl/7.47.0
Accept: /
Authorization: GatewayLogin token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
AS8D76F7A89S87D6F7A9SD876FA789SD78F6A7S9D78F6AS79DF87A6S7D9F7A6S7D9F78A6SD798F78679D786S789D78F6A7S9D78F6AS79DF876A7S89DF786AS9D87F69AS7D6FN1bWVyIn0.
KEuvjv3dmwkOhQ3JJ6dIShK8CG_fd2REApOGn1TRmgU"

CURL example

curl -v -H 'Authorization: GatewayLogin token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJsb2dpbl91c2VyX25hbWUiOiJ1c2VybmFtZSIsImlzX2ZpcnN0IjpmYWxzZSwiYXBwX2lkIjoiODVhOTY1ZjAtMGQ1NS00ZTBhLThiMWMtNjQ5YzRiMDFjNGZiIiwiYXBwX25hbWUiOiJHV0wiLCJ0aW1lX3N0YW1wIjoiMjAxOC0wOC0yMFQxNDoxMzo0MFoiLCJjYnNfdG9rZW4iOiJ5b3VyX3Rva2VuIiwiY2JzX2lkIjoieW91cl9jYnNfaWQiLCJzZXNzaW9uX2lkIjoiMTIzNDU2Nzg5In0.
bfWGWttEEcftiqrb71mE6Xy1tT_I-gmDPgjzvn6kC_k"' https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current

You should receive a response like:

{
  "user_id": "33fd104f-3e6f-4025-97cc-b76bbdc9148e",
  "email": "marko@tesobe.com",
  "provider_id": "marko.milic",
  "provider": "https://tesobe.openbankproject.com",
  "username": "marko.milic",
  "entitlements": {
    "list": []
  }
}

and custom response header i.e. OBP returns a new token in the custom response header called GatewayLogin (to the Gateway)

{
"username": "simonr",
"CBS_auth_token": "fapsoidfuipoi889w3ih", (Encrypted by OBP Adapter)
"timestamp": "timestamp",
"consumer_id": "123",
"consumer_name": "Name of Consumer"
}

GatewayLogin token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
AS8D76F7A89S87D6F7A9SD876FA789SD78F6A7S9D78F6AS79DF87A6S7D9F7A6S7D9F78A6SD798F78679D786S789D78F6A7S9D78F6AS79DF876A7S89DF786AS9D87F69AS7D6FN1bWVyIn0.
KEuvjv3dmwkOhQ3JJ6dIShK8CG_fd2REApOGn1TRmgU"

Example python script

import jwt
from datetime import datetime, timezone
import requests

env = 'local'
DATE_FORMAT = '%Y-%m-%dT%H:%M:%SZ'

obp_api_host = 'https://yourhost.com'
payload = {
    "login_user_name": "username",
    "is_first": False,
    "app_id": "85a965f0-0d55-4e0a-8b1c-649c4b01c4fb",
    "app_name": "Name",
    "time_stamp": datetime.now(timezone.utc).strftime(DATE_FORMAT),
    "cbs_token": "yourtokenforcbs",
    "cbs_id": "yourcbs_id",
    "session_id": "123456789"
}


token = jwt.encode(payload, 'your-at-least-256-bit-secret-token', algorithm='HS256').decode("utf-8")
authorization = 'GatewayLogin token="{}"'.format(token)
headers = {'Authorization': authorization}
url = obp_api_host + '/obp/v4.0.0/users/current'
req = requests.get(url, headers=headers)
print(req.text)

Under the hood

The file, GatewayLogin.scala handles the Gateway Login.

We:

-> Check if Props allow_gateway_login is true
  -> Check if GatewayLogin header exists
    -> Check if getRemoteIpAddress is OK
      -> Look for "token"
        -> If "is_first" is true -OR- CBS_auth_token is empty then, call CBS to get accounts

The CBS_auth_token (either the new one from CBS or existing one from previous token) is returned in the GatewayLogin custom response header.

More information

Parameter names and values are case sensitive.

Each parameter MUST NOT appear more than once per request.

Hola App log trace

   Please see:
			 [OBP Hola App Log Trace](https://github.com/OpenBankProject/OBP-API/wiki/Log-trace-of-the-Hola-App-performing-Georgian-flavour-of-Berlin-Group-authentication,-consent-generation-and-consuming-Berlin-Group-Account,-Balance-and-Transaction-resources)

JSON Schema Validation

JSON Schema is "a vocabulary that allows you to annotate and validate JSON documents".

By applying JSON Schema Validation to your OBP endpoints you can constrain POST and PUT request bodies. For example, you can set minimum / maximum lengths of fields and constrain values to certain lists or regular expressions.

See JSONSchema.org for more information about the JSON Schema standard.

To create a JSON Schema from an any JSON Request body you can use JSON Schema Net

(The video link below shows how to use that)

Note: OBP Dynamic Entities also use JSON Schema Validation so you don't need to additionally wrap the resulting endpoints with extra JSON Schema Validation but you could do.

You can apply JSON schema validations to any OBP endpoint's request body using the POST and PUT endpoints listed in the link below.

PLEASE SEE the following video explanation: JSON schema validation of request for Static and Dynamic Endpoints and Entities

Go Back to JSON Schema Validation APIs

Just In Time Entitlements

Just in Time Entitlements are NOT enabled on this instance.

This is how Just in Time Entitlements work:

If Just in Time Entitlements are enabled then OBP does the following:
If a user is trying to use a Role (via an endpoint) and the user could grant them selves the required Role(s), then OBP automatically grants the Role.
i.e. if the User already has canCreateEntitlementAtOneBank or canCreateEntitlementAtAnyBank then OBP will automatically grant a role that would be granted by a manual process anyway.
This speeds up the process of granting of roles. Certain roles are excluded from this automation:
- CanCreateEntitlementAtOneBank
- CanCreateEntitlementAtAnyBank
If create_just_in_time_entitlements is again set to false after it was true for a while, any auto granted Entitlements to roles are kept in place.
Note: In the entitlements model we set createdbyprocess=create_just_in_time_entitlements. For manual operations we set createdbyprocess=manual

To enable / disable this feature set the Props create_just_in_time_entitlements=true or false. The default is false.

KYC (Know Your Customer)

KYC is the process by which the Bank can be assured that the customer is who they say they are.

OBP provides a number of endpoints that KYC Apps can interact with in order to get and store relevant data and update the KYC status of a Customer.

For instance:

1) Use KYC documents to add information about passports, ID cards, driving licenses including:

  • customer_number
  • type (of document)
  • number (of document)
  • issue_date
  • issue_place
  • expiry_date

For more info see here.

2) Use KYC check to record a check of the customer via phone call, in person meeting or PEP database search.

KYC Checks store:

  • customer_number
  • date
  • how (FACE_TO_FACE_MEETING, PHONE_INTERVIEW, PEP_SEARCH)
  • staff_user_id (who recorded the record)
  • staff_name (who recorded the record)
  • satisfied (True/False)
  • comments

For more info see here.

3) Use KYC Media to add media (image or video etc.) related to:

A) the documents listed in KYC documents

B) media that identifies the user e.g. a video ident.

C) media that relates to a KYC check

KYC Media stores:

  • customer_number
  • type
  • url
  • date
  • relates_to_kyc_document_id
  • relates_to_kyc_check_id

For more information see here.

4) Use KYC status to update the KYC status of a customer following a meeting or using one of the above calls.

KYC status stores:

  • customer_number
  • ok (True/False)
  • date

For more information see here.

5) Use other Customer related endpoints shown here to check for known Addresses, contact details, Tax Residences etc.

License.id

Example value: ODbL-1.0

Description:

License.name

Example value: Open Database License

Description:

Message Doc

OBP can communicate with core banking systems (CBS) and other back end services using a "Connector -> Adapter" approach.

The OBP Connector is a core part of the OBP-API and is written in Scala / Java and potentially other JVM languages.

The OBP Connector implements multiple functions / methods in a style that satisfies a particular transport / protocol such as HTTP REST, Akka or Kafka.

An OBP Adapter is a separate software component written in any programming language that responds to requests from the OBP Connector.

Requests are sent by the Connector to the Adapter (or a message queue).

The Adapter must satisfy the Connector method's request for data (or return an error).

"Message Docs" are used to define and document the request / response structure.

Message Docs are visible in the API Explorer.

Message Docs are also available over the Message Doc endpoints.

Each Message Doc relates to one OBP function / method.

The Message Doc includes:

1) The Name of the internal OBP function / method e.g. getAccountsForUser
2) The Outbound Message structure.
3) The Inbound Message structure.
4) The Connector name which denotes the protocol / transport used (e.g. REST, Akka, Kafka etc)
5) Outbound / Inbound Topic
6) A list of required Inbound fields
7) A list of dependent endpoints.

The perspective is that of the OBP-API Connector i.e. the OBP Connector sends the message Out, and it receives the answer In.

The Outbound message contains several top level data structures:

1) The outboundAdapterCallContext

This tells the Adapter about the specific REST call that triggered the request and contains the correlationId to uniquely identify the REST call, the consumerId to identify the API Consumer (App) and a generalContext which is a list of key / value pairs that give the Adapter additional custom information about the call.

2) outboundAdapterAuthInfo

This tells the Adapter about the authenticated User that is making the call including: the userId, the userName, the userAuthContext (a list of key / value pairs that have been validated using SCA (see the UserAuthContext endpoints)) and other optional structures such as linked Customers and Views on Accounts to further identify the User.

3) The body

The body contains named fields that are specific to each Function / Message Doc.

For instance, getTransaction might send the bankId, accountId and transactionId so the Adapter can route the request based on bankId and check User permissions on the AccountId before retrieving a Transaction.

The Inbound message

The Inbound message is the reply or response from the Adapter and has the following structure:

1) The inboundAdapterCallContext

This is generally an echo of the outboundAdapterCallContext so the Connector can double check the target destination of the response.

2) The status

This contains information about status of the response including any errorCode and a list of backendMessages.

3) The data

This contains the named fields and their values which are specific to each Function / Message Doc.

The Outbound / Inbound Topics are used for routing in multi OBP instance / Kafka installations. (so OBP nodes only listen only to the correct Topics).

The dependent endpoints are listed to facilitate navigation in the API Explorer so integrators can test endpoints during integration.

Message Docs can be generated automatically using OBP code tools. Thus, it's possible to create custom connectors that follow specific protocol and structural patterns e.g. for message queue X over XML format Y.

Method Routing

Open Bank Project can have different connectors, to connect difference data sources.
We support several sources at the moment, eg: databases, rest services, stored procedures and kafka.

If OBP set connector=star, then you can use this method routing to switch the sources.
And we also provide the fields mapping in side the endpoints. If the fields in the source are different from connector,
then you can map the fields yourself.

The following videos are available:

*Method Routing Endpoints
*Method Routing Endpoints Mapping

Go Back to Method Routing APIs

OAuth 1.0a

The following steps will explain how to connect an instance of the Open Bank Project OAuth Server 1.0a. This authentication mechanism is necessary so a third party application can consume the Open Bank project API securely.

The following documentation is based on the OAuth 1.0a specification so if you need more details you can refer to it.

Before starting to interact with the API, third party applications needs to get OAuth keys (consumer key and secret key). You can register your application here to get those keys for interacting with real data. If you want to use the sandbox before handling real data, please register your application here

1) Obtain a request token

To start a sign in flow, the application must obtain a request token by sending a signed message to :

POST https://obp-api-sandbox.nmbbank.co.tz/oauth/initiate
  • oauth_callback: an absolute URI back to which the server will redirect the resource owner (user) when Authorization step is completed. If the application is unable to receive callbacks the parameter value MUST be set to “oob” (case sensitive), to indicate an out-of-band configuration.

  • oauth_consumer_key : The identifier portion of the client credentials (consumer key) which is obtained after application registration.

  • oauth_nonce : A nonce is a random string, uniquely generated by the client to allow the server to verify that a request has never been made before. The nonce value MUST be unique across all requests with the same timestamp, application credentials, and token combinations.

  • oauth_signature : the result of signing the request. Explained in detail here.

  • oauth_signature_method : The name of the signature method that will be used by the application to sign the request, as defined in OAuth protocol. The Open Bank Project OAuth server support "SHA1" and "SHA256" so the parameter MUST be set to “HMAC-SHA1" or “HMAC-SHA256”

  • oauth_timestamp : The timestamp value MUST be a positive integer and is expressed in the number of seconds since January 1, 1970 00:00:00 GMT.

  • oauth_version : OPTIONAL. If present, MUST be set to "1.0". Provides the version of the authentication process as defined in the OAuth 1.0 protocol specification.

Example:

POST /oauth/initiate HTTP/1.1

Host: https://obp-api-sandbox.nmbbank.co.tz

Authorization: OAuth

oauth_callback="http%3A%2F%2Fprinter.example.com%2Fready",

oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",

oauth_nonce="ea9ec8429b68d6b77cd5600adbbb0456",

oauth_signature="F1Li3tvehgcraF8DMJ7OyxO4w9Y%3D",

oauth_signature_method="HMAC-SHA256",

oauth_timestamp="1318467427",

oauth_version="1.0"

important: We will explain below in the "signature" section how to calculate the value of the "oauth_signature" field.

Note : line breaks are for display purposes only, the application MUST send the parameters on one line and the only separator between the parameters is a coma “,”.

The server validates the request and replies with a set of temporary credentials in the body of the HTTP response.

Example (line breaks are for display purposes only) :

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=hh5s93j4hdidpola&oauth_token_secret=hdhd0244k9j7ao03&oauth_callback_confirmed=true

The application should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the oauth_token, oauth_token_secret, and oauth_callback_confirmed parameters. The application should verify that oauth_callback_confirmed is true and store the other two values for the next steps.

2) Redirect the user

The next step is to direct the user to Open Bank Project so that he may complete the authentication.

Direct the user to :

GET oauth/authorize

and the request token obtained in step 1 should be passed as the oauth_token parameter.

The most seamless way for a website to implement this would be to issue a HTTP 302 redirect as the response to the original request. Mobile and desktop applications should open a new browser window or direct to the URL via an embedded web view.

Example :

https://obp-api-sandbox.nmbbank.co.tz/oauth/authorize?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0

Upon a successful authentication, the callback URL would receive a request containing the oauth_token and oauth_verifier parameters. The application should verify that the token matches the request token received in step 1.

If the callback URL was not specified (oob) than the verifier will be shown in the page and the user has to enter it into the application manually.

3) Convert the request token to an access token

To convert the request token into a usable access token, the application must make a:

POST https://obp-api-sandbox.nmbbank.co.tz/oauth/token

request containing the oauth_verifier value obtained in step 2. The request token is also passed as oauth_token parameter of the header.

Note : The oauth_callback_url parameter is not necessary any more.

Example :

POST /oauth/token HTTP/1.1

Host: https://obp-api-sandbox.nmbbank.co.tz

Authorization: OAuth

oauth_verifier="9312832",

oauth_token=”aze2342352aze”,

oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",

oauth_nonce="ea9ec8429b68d6b77cd5600adbbb0456",

oauth_signature="F1Li3tvehgcraF8DMJ7OyxO4w9Y%3D",

oauth_signature_method="HMAC-SHA256",

oauth_timestamp="1318467427",

oauth_version="1.0"

Like the step 1, a successful response contains the oauth_token & oauth_token_secret and they should be stored and used for future authenticated requests to the OBP API.

The application can now use the access token to access protected resources.

4) Access protected resources

Once the application has an a access token and secret token, it can access protected resources. The request is the same as in step 3 except the oauth_verifer which MUST not be included in the header.

Please see the API documentation for more details on how to access protected resources.

Recommended OAuth 1.0 libraries:

If you want to use a OAuth library to handle the OAuth process for your application, we have successfully tested these ones:

  • JAVA:

signpost. Warning any version below 1.2.1.2 probably will not work. Version 1.2 which is the current Maven version seems to cause problems.

  • PHP:

OAuth Consumer And Server Library

  • Scala:

Dispatch

  • OBP SDKs / examples of client code with OAuth:

OBP SDKs

Examples :

To show the OAuth integration in concrete examples, please check out these projects listed here:
Hello-OBP-OAuth1.0a-LANGUAGE/PLATFORM

Signature :

According to the section-3.4 in the OAuth 1.0 protocol specification the signature computation is done following theses steps :

a) Signature Base String :

The signature base string is a consistent, reproducible concatenation of several of the HTTP request elements into a single string. The string is used as an input to the signature methods.

The signature base string includes the following components of the HTTP request:

  • The HTTP request method (e.g., "GET", "POST", etc.).

  • The authority as declared by the HTTP "Host" request header field.

  • The path and query components of the request resource URI.

  • he protocol parameters excluding the "oauth_signature".

The signature base string does not cover the entire HTTP request. Most notably, it does not include the entity-body in most requests, nor does it include most HTTP entity-headers.

The signature base string is constructed by concatenating together, in order, the following HTTP request elements:

  1. The HTTP request method in uppercase. For example: "HEAD", "GET", "POST", etc. If the request uses a custom HTTP method, it MUST be encoded (Section 3.6).

  2. An "&" character (ASCII code 38).

  3. The base string URI from Section 3.4.1.2, after being encoded (Section 3.6).

  4. An "&" character (ASCII code 38).

  5. The request parameters as normalized in Section 3.4.1.3.2, after being encoded (Section 3.6).

Explained shortly below the example.

Example:

POST /oauth/token HTTP/1.1
Host: https://obp-api-sandbox.nmbbank.co.tz
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_consumer_key="91919",
oauth_token="OGESD9MrWQEGPXOyPjHCRrCw7BPelWJjnomibV6bePU",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="1340878170",
oauth_nonce="DFXOQFZVK8K46KDR11",
oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

Is represented by the following signature base string (line breaks are for display purposes only):

POST&https%3A%2F%2Fhttps://obp-api-sandbox.nmbbank.co.tz&oauth_consumer_key%3D91919%26oauth_nonce%3DDFXOQFZVK8K46KDR11%26oauth_signature_method%3Dhmac-sha256%26oauth_timestamp%3D1340878170%26oauth_token%3DOGESD9MrWQEGPXOyPjHCRrCw7BPelWJjnomibV6bePU%26oauth_verifier%3DT0dXUDBZR09LUVlGTU9NSlhIUUc%26oauth_version%3D1

The request parameters normalization :

  1. The name and value of each parameter are encoded Section 3.6.

  2. The parameters are sorted by name, using ascending byte value ordering.

  3. The name of each parameter is concatenated to its corresponding value using an "=" character (ASCII code 61) as a separator, even if the value is empty.

  4. The sorted name/value pairs are concatenated together into a single string by using an "&" character (ASCII code 38) as separator.

B) Signing the request :

The Open Bank Project OAuth 1.0 implementation uses the “HMAC-SHA1” and “HMAC-SHA256” as signing methods. The key to sign the base string is the concatenation of the consumer secret and the token secret with the “&” character in the middle like this: oauth_consumer_secret&oauth_token_secret, in the first step the application does not have yet a token so it will be an empty string.

The signature that results from the signature process MUST be encoded in base 64 also since the protocol requires encoding all the OAuth parameters.

Illustration of integration with a bank back-end :

The following link shows how the integration of the OAuth process would be with a bank back-end: https://github.com/OpenBankProject/OBP-API/wiki/OAuth-Integration-Illustration

OAuth 2

OAuth2 is allowed on this instance.

OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service, in this case any OBP REST call. It works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. OAuth 2 provides authorization flows for web and desktop applications, and mobile devices.

OAuth2 Roles

The following is a general introduction to a so called "3 legged OAuth2" flow:

  • Resource Owner
  • Client
  • Resource Server
  • Authorization Server

Resource Owner: User

The resource owner is the user who authorizes an application to access their account. The application's access to the user's account is limited to the "scope" of the authorization granted (e.g. openid).

Authorization Server: API

The authorization server verifies the identity of the user then issues access tokens to the application. E.g. Hydra

Resource Server: API

The resource server hosts the protected user resources. E.g. OBP-API

Client: Application

The client is the application that wants to access the user's resource. In order to do that, it must be authorized by the user, and the authorization must be validated by the Authorization Server: API.

Authorization Grant

OAuth 2 defines four grant types, each of which is useful in different cases:

  • Authorization Code: used with server-side Applications

  • Implicit: used with Mobile Apps or Web Applications (applications that run on the user's device)

  • Resource Owner Password Credentials: used with trusted Applications, such as those owned by the service itself

  • Client Credentials: used with Applications API access

Step 1: Get your App key

Sign up or login as a developer

Register your App key HERE

Copy and paste the CLIENT ID (AKA CONSUMER KEY), CLIENT SECRET (AKA CONSUMER SECRET) and REDIRECT_URL for the subsequent steps below.

Step 2: Initiate the OAuth 2.0 / OpenID Connect Flow

Once you have registered your App you should initiate the OAuth2 / OIDC flow using the following URL

https://obp-oauth2-sandbox.nmbbank.co.tz/hydra-public/oauth2/auth

WITH THE following parameters:

https://obp-oauth2-sandbox.nmbbank.co.tz/hydra-public/oauth2/auth?client_id=YOUR-CLIENT-ID&response_type=code&state=GENERATED_BY_YOUR_APP&scope=openid+offline+ReadAccountsBasic+ReadAccountsDetail+ReadBalances+ReadTransactionsBasic+ReadTransactionsDebits+ReadTransactionsDetail&redirect_uri=https%3A%2F%2FYOUR-APP.com%2Fmain.html

Step 3: Exchange the authorisation code for an access token

The token endpoint is:

https://obp-oauth2-sandbox.nmbbank.co.tz/hydra-public/oauth2/token

For further information please see here

In this sandbox, this will cause the following flow:

1) The User is authorised using OAuth2 / OpenID Connect against the banks authentication system
2) The User grants consent to the App on the bank's Consent page.
3) The User grants access to one or more accounts that they own on the bank's Account Selection page
4) The User is redirected back to the App where they can now see the Accounts they have selected.

An example Consent Testing App (Hola) using this flow can be found here

OAuth 2 with Google

OAuth2 is allowed on this instance.

OpenID Connect with Google

Introduction

Google's OAuth 2.0 APIs can be used for both authentication and authorization. This document describes our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification, and is OpenID Certified.
For complete documentation please refer to the official doc's page: OpenID Connect

OpenID Connect with Google Image

Obtain OAuth 2.0 credentials

Please refer to the official doc's page: OpenID Connect
In case you use Google's OAuth 2.0 Playground
example of an response is shown below:
{
"access_token": "ya29.a0Adw1xeVr_WAYaipiH_6QKCFjIFsnZxW7kbxA8a2RU_uy5meEufErwPDLSHMga8IEQghNSX2GbkOfZUQb6j_fMGHL_HaW3RoULZq5AayUdEjI9bC4TMe-Nd4cZR17C0Rg3GLNzuHTXXe05UyMmNODZ6Up0aXZBBTHl-4",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE1NDFkNmVmMDIyZDc3YTIzMThmN2RkNjU3ZjI3NzkzMjAzYmVkNGEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJhdWQiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJzdWIiOiIxMTM5NjY4NTQyNDU3ODA4OTI5NTkiLCJlbWFpbCI6Im1hcmtvLm1pbGljLnNyYmlqYUBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYXRfaGFzaCI6ImtrcENIWUFaSTZVOFZiZEJsRHNfX1EiLCJuYW1lIjoiTWFya28gTWlsacSHIiwicGljdHVyZSI6Imh0dHBzOi8vbGg1Lmdvb2dsZXVzZXJjb250ZW50LmNvbS8tWGQ0NGhuSjZURG8vQUFBQUFBQUFBQUkvQUFBQUFBQUFBQUEvQUtGMDVuQ1pyaTdmWHdkUUhuZUNwN09pTVh1WGlOMkpVQS9zOTYtYy9waG90by5qcGciLCJnaXZlbl9uYW1lIjoiTWFya28iLCJmYW1pbHlfbmFtZSI6Ik1pbGnEhyIsImxvY2FsZSI6ImVuIiwiaWF0IjoxNTg0NTIxNDU3LCJleHAiOjE1ODQ1MjUwNTd9.LgwY-OhltYS2p91l2Lt4u5lUR5blR7L8097J0ZpK0GyxWxOlnhSouk9MRMmyfSGuYfWKBtdSUy3Esaphk2f7wpLS-wBx3KJpvrXhgbsyemt9s7eu5bAdHaCteO8MqHPjbU9tych8iH0tA1MSL_tVZ73hy56rS2irzIC33wYDoBf8C5nEOd2uzQ758ydK5QvvdFwRgkLhKDS8vq2qVJTWgtk9VVd5JwJ5OfiVimXfGUzNJmGreEJKj14iUj-78REybpUbI9mGevRhjLPhs51Uc9j-SsdRMymVbVhVxlbsWAPTpjLAJnOodeHzAvmKFkOUfahQHHctx4fl8V3PVYf1aA",
"expires_in": 3599,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email openid",
"refresh_token": "1//04w7RCdl9ZnG-CgYIARAAGAQSNwF-L9IrNZVxs6fliP7xAlHjKcZpfpw7JoYyBsvxKMD7n0xyB74G8aRlFoBkkCbloETrWMU6yOA"
}
Note: The OAuth Playground will automatically revoke refresh tokens after 24h. You can avoid this by specifying your own application OAuth credentials using the Configuration panel.

An ID token's payload

	{
	"iss": "https://accounts.google.com",
	"azp": "407408718192.apps.googleusercontent.com",
	"aud": "407408718192.apps.googleusercontent.com",
	"sub": "113966854245780892959",
	"email": "marko.milic.srbija@gmail.com",
	"email_verified": true,
	"at_hash": "nGKRToKNnVA28H6MhwXBxw",
	"name": "Marko Milić",
	"picture": "https://lh5.googleusercontent.com/-Xd44hnJ6TDo/AAAAAAAAAAI/AAAAAAAAAAA/AKxrwcadwzhm4N4tWk5E8Avxi-ZK6ks4qg/s96-c/photo.jpg",
	"given_name": "Marko",
	"family_name": "Milić",
	locale: "en",
	"iat": 1547705691,
	"exp": 1547709291
	}

Try a REST call using the authorization's header

	Using your favorite http client:

	GET /obp/v3.0.0/users/current

Body

Leave Empty!

Headers:

	Authorization: Bearer ID_TOKEN

Here is it all together:

GET /obp/v3.0.0/users/current HTTP/1.1
	Host: https://obp-api-sandbox.nmbbank.co.tz
	Authorization: Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjA4ZDMyNDVjNjJmODZiNjM2MmFmY2JiZmZlMWQwNjk4MjZkZDFkYzEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJhdWQiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJzdWIiOiIxMTM5NjY4NTQyNDU3ODA4OTI5NTkiLCJlbWFpbCI6Im1hcmtvLm1pbGljLnNyYmlqYUBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYXRfaGFzaCI6IkFvYVNGQTlVTTdCSGg3YWZYNGp2TmciLCJuYW1lIjoiTWFya28gTWlsacSHIiwicGljdHVyZSI6Imh0dHBzOi8vbGg1Lmdvb2dsZXVzZXJjb250ZW50LmNvbS8tWGQ0NGhuSjZURG8vQUFBQUFBQUFBQUkvQUFBQUFBQUFBQUEvQUt4cndjYWR3emhtNE40dFdrNUU4QXZ4aS1aSzZrczRxZy9zOTYtYy9waG90by5qcGciLCJnaXZlbl9uYW1lIjoiTWFya28iLCJmYW1pbHlfbmFtZSI6Ik1pbGnEhyIsImxvY2FsZSI6ImVuIiwiaWF0IjoxNTQ3NzExMTE1LCJleHAiOjE1NDc3MTQ3MTV9.MKsyecCSKS4Y0C8R4JP0J0d2Oa-xahvMAbtfFrGHncTm8xBgeaNb50XSJn20ak1YyA8hZiRP2M3el0f4eIVQZsMMa22MrwaiL8pLb1zGfawDLPb1RvOmoCWTDJGc_s1qQMlyc21Wenr9rjuu1bQCerGTYM6M0Aq-Uu_GT0lCEjz5WVDI5xDUf4Mhdi8HYq7UQ1kGz1gQFiBm5nI3_xtYm75EfXFeDg3TejaMmy36NpgtwN_vwpHByoHE5BoTl2J55rJ2creZZ7CmtZttm-9HsT6v1vxT8zi0RXObFrZSk-LgfF0tJQcGZ5LXQZL0yMKXPQVFIMCg8J0Gg7l_QACkCA
	Cache-Control: no-cache

CURL example:

	curl -X GET
	https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current
	-H 'Authorization: Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjA4ZDMyNDVjNjJmODZiNjM2MmFmY2JiZmZlMWQwNjk4MjZkZDFkYzEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJhenAiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJhdWQiOiI0MDc0MDg3MTgxOTIuYXBwcy5nb29nbGV1c2VyY29udGVudC5jb20iLCJzdWIiOiIxMTM5NjY4NTQyNDU3ODA4OTI5NTkiLCJlbWFpbCI6Im1hcmtvLm1pbGljLnNyYmlqYUBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYXRfaGFzaCI6IkFvYVNGQTlVTTdCSGg3YWZYNGp2TmciLCJuYW1lIjoiTWFya28gTWlsacSHIiwicGljdHVyZSI6Imh0dHBzOi8vbGg1Lmdvb2dsZXVzZXJjb250ZW50LmNvbS8tWGQ0NGhuSjZURG8vQUFBQUFBQUFBQUkvQUFBQUFBQUFBQUEvQUt4cndjYWR3emhtNE40dFdrNUU4QXZ4aS1aSzZrczRxZy9zOTYtYy9waG90by5qcGciLCJnaXZlbl9uYW1lIjoiTWFya28iLCJmYW1pbHlfbmFtZSI6Ik1pbGnEhyIsImxvY2FsZSI6ImVuIiwiaWF0IjoxNTQ3NzExMTE1LCJleHAiOjE1NDc3MTQ3MTV9.MKsyecCSKS4Y0C8R4JP0J0d2Oa-xahvMAbtfFrGHncTm8xBgeaNb50XSJn20ak1YyA8hZiRP2M3el0f4eIVQZsMMa22MrwaiL8pLb1zGfawDLPb1RvOmoCWTDJGc_s1qQMlyc21Wenr9rjuu1bQCerGTYM6M0Aq-Uu_GT0lCEjz5WVDI5xDUf4Mhdi8HYq7UQ1kGz1gQFiBm5nI3_xtYm75EfXFeDg3TejaMmy36NpgtwN_vwpHByoHE5BoTl2J55rJ2creZZ7CmtZttm-9HsT6v1vxT8zi0RXObFrZSk-LgfF0tJQcGZ5LXQZL0yMKXPQVFIMCg8J0Gg7l_QACkCA'
	-H 'Cache-Control: no-cache'
	-H 'Postman-Token: aa812d04-eddd-4752-adb7-4d56b3a98f36'

And we get the response:

	{
		"user_id": "6d411bce-50c1-4eb8-b8b0-3953e4211773",
		"email": "marko.milic.srbija@gmail.com",
		"provider_id": "113966854245780892959",
		"provider": "https://accounts.google.com",
		"username": "Marko Milić",
		"entitlements": {
		"list": []
	}
	}

SCA (Strong Customer Authentication)

SCA is the process by which a Customer of the Bank securely identifies him/her self to the Bank.

Generally this involves using an Out Of Band (OOB) form of communication e.g. a One Time Password (OTP) / code sent to a mobile phone.

In the OBP APIs, SCA is invoked during Transaction Requests and Consent creation.

See the following endpoints:

Create Consent via SMS
Create Consent via Email (for testing purposes)
Answer Consent Challenge

Create Transaction Request
Answer Transaction Request Challenge

Possible SCA flows:

obp-sca-image-1

Scenario 1: Onboarding a User

1) Create a user

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/users

Body:

{  "email":"ellie@example.com",  "username":"ellie",  "password":"P@55w0RD123",  "first_name":"Ellie",  "last_name":"Williams"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

Please note the user_id

2) Create customer

Requires CanCreateCustomer and CanCreateUserCustomerLink roles

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/customers

Body:

{  "legal_name":"Eveline Tripman",  "mobile_phone_number":"+44 07972 444 876",  "email":"eveline@example.com",  "face_image":{    "url":"www.openbankproject",    "date":"1100-01-01T00:00:00Z"  },  "date_of_birth":"1100-01-01T00:00:00Z",  "relationship_status":"single",  "dependants":10,  "dob_of_dependants":["1100-01-01T00:00:00Z"],  "credit_rating":{    "rating":"OBP",    "source":"OBP"  },  "credit_limit":{    "currency":"EUR",    "amount":"10"  },  "highest_education_attained":"Master",  "employment_status":"worker",  "kyc_status":true,  "last_ok_date":"1100-01-01T00:00:00Z",  "title":"Dr.",  "branch_id":"DERBY6",  "name_suffix":"Sr"}

Headers:

Content-Type:  application/json

Authorization: directlogin token="your-token-from-direct-login"

3) List customers for the user

Action:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/users/current/customers

Body:

Leave empty!

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

4) Create user customer link

Requires CanCreateCustomer and CanCreateUserCustomerLink roles

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/user_customer_links

Body:

{ "user_customer_link_id":"String", "customer_id":"customer-id-from-step-2", "user_id":"user-id-from-step-1", "date_inserted":"2018-03-22T00:08:00Z", "is_active":true }

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

5) Create account

Requires CanCreateAccount role

Action:

PUT https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/ACCOUNT_ID

Body:

{  "user_id":"userid-from-step-1",  "label":"My Account",  "product_code":"AC",  "balance":{    "currency":"EUR",    "amount":"10"  },  "branch_id":"DERBY6",  "account_routing":{    "scheme":"AccountNumber",    "address":"4930396"  },  "account_attributes":[{    "product_code":"saving1",    "account_attribute_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f",    "name":"OVERDRAFT_START_DATE",    "type":"DATE_WITH_DAY",    "value":"2012-04-23"  }]}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

6) List accounts

Action:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/my/banks/BANK_ID/accounts/account-id-from-step-5/account

Body:

Leave empty!

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

7) Create card

Requires CanCreateCardsForBank role

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/management/banks/BANK_ID/cards

Body:

{ "card_number":"364435172576215", "card_type":"Credit", "name_on_card":"SusanSmith", "issue_number":"1", "serial_number":"1324234", "valid_from_date":"2017-09-19T00:00:00Z", "expires_date":"2017-09-19T00:00:00Z", "enabled":true, "technology":"technology1", "networks":["network1","network2"], "allows":["credit","debit"], "account_id":"account_id from step 5", "replacement":{ "requested_date":"2017-09-19T00:00:00Z", "reason_requested":"RENEW" }, "pin_reset":[{ "requested_date":"2017-09-19T00:00:00Z", "reason_requested":"FORGOT" },{ "requested_date":"2020-01-18T16:39:23Z", "reason_requested":"GOOD_SECURITY_PRACTICE" }], "collected":"2017-09-19T00:00:00Z", "posted":"2017-09-19T00:00:00Z", "customer_id":"customer_id from step 2"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct0login"

8) List cards

Action:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/cards

Body:

Leave empty!

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct0login"

Scenario 2: Create a Public Account

1) Create account

Create an account as described in Step 5 of section Onboarding a user

2) Create a view

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/banks/BANK_ID/accounts/your-account-id-from-step-1/views

Body:

{ "name":"_test", "description":"This view is for family", "metadata_view":"_test", "is_public":true, "which_alias_to_use":"family", "hide_metadata_if_alias_used":false, "allowed_actions":["can_see_transaction_this_bank_account","can_see_transaction_other_bank_account","can_see_transaction_metadata","can_see_transaction_label","can_see_transaction_amount","can_see_transaction_type","can_see_transaction_currency","can_see_transaction_start_date","can_see_transaction_finish_date","can_see_transaction_balance","can_see_comments","can_see_narrative","can_see_tags","can_see_images","can_see_bank_account_owners","can_see_bank_account_type","can_see_bank_account_balance","can_see_bank_account_currency","can_see_bank_account_label","can_see_bank_account_national_identifier","can_see_bank_account_swift_bic","can_see_bank_account_iban","can_see_bank_account_number","can_see_bank_account_bank_name","can_see_other_account_national_identifier","can_see_other_account_swift_bic","can_see_other_account_iban","can_see_other_account_bank_name","can_see_other_account_number","can_see_other_account_metadata","can_see_other_account_kind","can_see_more_info","can_see_url","can_see_image_url","can_see_open_corporates_url","can_see_corporate_location","can_see_physical_location","can_see_public_alias","can_see_private_alias","can_add_more_info","can_add_url","can_add_image_url","can_add_open_corporates_url","can_add_corporate_location","can_add_physical_location","can_add_public_alias","can_add_private_alias","can_delete_corporate_location","can_delete_physical_location","can_edit_narrative","can_add_comment","can_delete_comment","can_add_tag","can_delete_tag","can_add_image","can_delete_image","can_add_where_tag","can_see_where_tag","can_delete_where_tag","can_create_counterparty","can_see_bank_routing_scheme","can_see_bank_routing_address","can_see_bank_account_routing_scheme","can_see_bank_account_routing_address","can_see_other_bank_routing_scheme","can_see_other_bank_routing_address","can_see_other_account_routing_scheme","can_see_other_account_routing_address","can_query_available_funds","can_add_transaction_request_to_own_account","can_add_transaction_request_to_any_account","can_see_bank_account_credit_limit","can_create_direct_debit","can_create_standing_order"]} |
Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

3) Grant user access to view

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/banks/BANK_ID/accounts/your-account-id-from-step-1/permissions/PROVIDER/PROVIDER_ID/views/view-id-from-step-2

Body:

{  "json_string":"{}"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

Scenario 3: Create counterparty and make payment

1) Create counterparty

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/account-id-from-account-creation/VIEW_ID/counterparties

Body:

{ "name":"CounterpartyName", "description":"My landlord", "other_account_routing_scheme":"accountNumber", "other_account_routing_address":"7987987-2348987-234234", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "other_bank_routing_scheme":"bankCode", "other_bank_routing_address":"10", "other_branch_routing_scheme":"branchNumber", "other_branch_routing_address":"10010", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }]} |
Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

2) Make payment by SEPA

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/VIEW_ID/transaction-request-types/SEPA/transaction-requests

Body:

{  "value":{    "currency":"EUR",    "amount":"10"  },  "to":{    "iban":"123"  },  "description":"This is a SEPA Transaction Request",  "charge_policy":"SHARED"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"        |

3) Make payment by COUNTERPARTY

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/VIEW_ID/transaction-request-types/COUNTERPARTY/transaction-requests

Body:

{  "to":{    "counterparty_id":"counterparty-id-from-step-1"  },  "value":{    "currency":"EUR",    "amount":"10"  },  "description":"A description for the transaction to the counterparty",  "charge_policy":"SHARED"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

Scenario 4: Grant account access to another User

1) Create account

Create an account as described in Step 5 of section Onboarding a user

2) Create a view (private)

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/your-account-id-from-step-1/views

Body:

{  "name":"_test", "description":"good", "is_public":false, "which_alias_to_use":"accountant", "hide_metadata_if_alias_used":false,  "allowed_actions": ["can_see_transaction_this_bank_account", "can_see_transaction_other_bank_account", "can_see_transaction_metadata", "can_see_transaction_label", "can_see_transaction_amount", "can_see_transaction_type", "can_see_transaction_currency", "can_see_transaction_start_date", "can_see_transaction_finish_date", "can_see_transaction_balance", "can_see_comments", "can_see_narrative", "can_see_tags", "can_see_images", "can_see_bank_account_owners", "can_see_bank_account_type", "can_see_bank_account_balance", "can_see_bank_account_currency", "can_see_bank_account_label", "can_see_bank_account_national_identifier", "can_see_bank_account_swift_bic", "can_see_bank_account_iban", "can_see_bank_account_number", "can_see_bank_account_bank_name", "can_see_other_account_national_identifier", "can_see_other_account_swift_bic", "can_see_other_account_iban", "can_see_other_account_bank_name", "can_see_other_account_number", "can_see_other_account_metadata", "can_see_other_account_kind", "can_see_more_info", "can_see_url", "can_see_image_url", "can_see_open_corporates_url", "can_see_corporate_location", "can_see_physical_location", "can_see_public_alias", "can_see_private_alias", "can_add_more_info", "can_add_url", "can_add_image_url", "can_add_open_corporates_url", "can_add_corporate_location", "can_add_physical_location", "can_add_public_alias", "can_add_private_alias", "can_delete_corporate_location", "can_delete_physical_location", "can_edit_narrative", "can_add_comment", "can_delete_comment", "can_add_tag", "can_delete_tag", "can_add_image", "can_delete_image", "can_add_where_tag", "can_see_where_tag", "can_delete_where_tag", "can_create_counterparty", "can_see_bank_routing_scheme", "can_see_bank_routing_address", "can_see_bank_account_routing_scheme", "can_see_bank_account_routing_address", "can_see_other_bank_routing_scheme", "can_see_other_bank_routing_address", "can_see_other_account_routing_scheme", "can_see_other_account_routing_address"]}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

3) Get User (Current)

Action:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/users/current

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

4) Grant user access to himself

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/your-account-id-from-step-1/account-access/grant 

Body:

{  "user_id":"your-user-id-from-step3",  "view":{    "view_id":"_test",    "is_system":false  }}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"			

5) Grant user access to view to another user

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v4.0.0/banks/BANK_ID/accounts/your-account-id-from-step-1/account-access/grant 

Body:

{  "user_id":"another-user-id",  "view":{    "view_id":"_test",    "is_system":false  }}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token"

Scenario 5: Onboarding a User using Auth Context

1) Create a user

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users

Body:

{  "email":"ellie@example.com",  "username":"ellie",  "password":"P@55w0RD123",  "first_name":"Ellie",  "last_name":"Williams"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

Please note the user_id

2) Create User Auth Context

These key value pairs will be propagated over connector to adapter and to bank. So the bank can use these key value paris
to map obp user to real bank customer.

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v4.0.0/users/USER_ID/auth-context

Body:

{  "key":"CUSTOMER_NUMBER",  "value":"78987432"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

3) Create customer

Requires CanCreateCustomer or canCreateCustomerAtAnyBank roles

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/v3.1.0/banks/BANK_ID/customers

Body:

{  "user_id":"user-id-from-step-1", "customer_number":"687687678", "legal_name":"NONE",  "mobile_phone_number":"+44 07972 444 876", "email":"person@example.com", "face_image":{    "url":"www.openbankproject",    "date":"2013-01-22T00:08:00Z"  },  "date_of_birth":"2013-01-22T00:08:00Z",  "relationship_status":"Single",  "dependants":5,  "dob_of_dependants":["2013-01-22T00:08:00Z"],  "credit_rating":{    "rating":"OBP",    "source":"OBP"  },  "credit_limit":{    "currency":"EUR",    "amount":"10"  },  "highest_education_attained":"Bachelor’s Degree",  "employment_status":"Employed",  "kyc_status":true,  "last_ok_date":"2013-01-22T00:08:00Z"}

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

4) Get Customers for Current User

Action:

GET https://obp-api-sandbox.nmbbank.co.tz/obp/v3.0.0/users/current/customers

Body:

Leave empty!

Headers:

Content-Type:  application/json

Authorization: DirectLogin token="your-token-from-direct-login"

Scenario 6: Update credit score based on transaction and device data.

1) Use Case

As an App developer you want to give a Credit Rating to a Customer based on their Transactions and also device data.

2) Solution Overview:

In general your application will need to:
1) Loop through Customers
2) For each Customer, get its related Users and associated device data
3) For each Customer or User get the related accounts
4) For each Account, get its Transaction data
5) Update the Credit Rating and Credit Rating Readiness score of the Customer.

3) Authentication and Authorisation

Depending on the configuration of this OBP instance, the Consumer will need Scopes and / or the User will need Entitlements.
To get started, we suggest requesting Entitlements via the API Explorer.

4) Endpoints

  • Get Customers (minimal). Click here for documentation.

The above endpoints return a list of bank_id and customer_id which can be used for getting correlated Users and their attributes:

  • Get Correlated Users for a Customer. Click here for documentation.

Then get Accounts related to a Customer:

  • GET Accounts Minimal for a Customer. Click here for documentation.

Once you have the list of bank_ids and account_ids, you can get their transactions which include tags for each transaction:

  • GET Firehose Transactions. Click here for documentation.

After your processing of the data you can update the Credit Score:

  • Update Credit Score. Click here for documentation.

You can create a CREDIT_SCORE_READINESS attribute using the following endpoint:

  • Create Customer Attribute. Click here for documentation.

And update it here:

  • Update Customer Attribute. Click here for documentation.

Scenario 7: Onboarding a User with multiple User Auth Context records

1) Assuming a User is registered.

The User can authenticate using OAuth, OIDC, Direct Login etc.

2) Create a first User Auth Context record e.g. ACCOUNT_NUMBER

The setting of the first User Auth Context record for a User, typically involves sending an SMS to the User.
The phone number used for the SMS is retrieved from the bank's Core Banking System via an Account Number to Phone Number lookup.
If this step succeeds we can be reasonably confident that the User who initiated it has access to a SIM card that can use the Phone Number linked to the Bank Account on the Core Banking System.

Action: Create User Auth Context Update Request

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v5.0.0/banks/BANK_ID/users/current/auth-context-updates/SMS

Body:

{  "key":"ACCOUNT_NUMBER",  "value":"78987432"}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

When customer get the the challenge answer from SMS, then need to call Answer Auth Context Update Challenge to varify the challenge.
Then the customer create the 1st User Auth Context successfully.

Action: Answer Auth Context Update Challenge

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v5.0.0/banks/BANK_ID/users/current/auth-context-updates/AUTH_CONTEXT_UPDATE_ID/challenge

Body:

{  "answer": "12345678"}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

3) Create a second User Auth Context record e.g. SMALL_PAYMENT_VERIFIED

Once the first User Auth Context record is set, we can require the App to set a second record which builds on the information of the first.

Action: Create User Auth Context Update Request

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v5.0.0/banks/BANK_ID/users/current/auth-context-updates/SMS

Body:

{  "key":"SMALL_PAYMENT_VERIFIED",  "value":"78987432"}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

Following Create User Auth Context Update Request request the API will send a small payment with a random code from the Users bank account specified in the SMALL_PAYMENT_VERIFIED key value.

In order to answer the challenge, the User must have access to the online banking statement (or some other App that already can read transactions in realtime) so they can read the code in the description of the payment.

Then Action:Answer Auth Context Update Challenge

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v5.0.0/banks/BANK_ID/users/current/auth-context-updates/AUTH_CONTEXT_UPDATE_ID/challenge

Body:

{  "answer": "12345678"}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

Note! The above logic must be encoded in a dynamic connector method for the OBP internal function validateUserAuthContextUpdateRequest which is used by the endpoint Create User Auth Context Update Request See the next step.

4) Create or Update Connector Method for validateUserAuthContextUpdateRequest

Using this endpoint you can modify the Scala logic

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v4.0.0/management/connector-methods

Body:

{  "method_name":"validateUserAuthContextUpdateRequest",  "method_body":"%20%20%20%20%20%20Future.successful%28%0A%20%20%20%20%20%20%20%20Full%28%28BankCommons%28%0A%20%20%20%20%20%20%20%20%20%20BankId%28%22Hello%20bank%20id%22%29%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%221%22%2C%0A%20%20%20%20%20%20%20%20%20%20%228%22%0A%20%20%20%20%20%20%20%20%29%2C%20None%29%29%0A%20%20%20%20%20%20%29"}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

5) Allow automated access to the App with Create Consent (SMS)

Following the creation of User Auth Context records, OBP will create the relevant Account Access Views which allows the User to access their account(s).
The App can then request an OBP consent which can be used as a bearer token and have automated access to the accounts.
The Consent can be deleted at any time by the User.

The Consent can have access to everything the User has access to, or a subset of this.

Action:

POST https://obp-api-sandbox.nmbbank.co.tz/obp/obp/v4.0.0/banks/BANK_ID/my/consents/SMS

Body:

{  "everything":false,  "views":[{    "bank_id":"gh.29.uk",    "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",    "view_id":"owner"  }],  "entitlements":[{    "bank_id":"gh.29.uk",    "role_name":"CanGetCustomer"  }],  "consumer_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",  "phone_number":"+44 07972 444 876",  "valid_from":"2022-04-29T10:40:03Z",  "time_to_live":3600}

Headers:

Content-Type:  application/json

directlogin: token="your-token-from-direct-login"

OBP User Auth Context, Views, Consents 2022

Space

In OBP, if you have access to a "Space", you have access to a set of Dynamic Endpoints and Dynamic Entities that belong to that Space.
Internally, Spaces are defined as a "Banks" thus Spaces are synonymous with OBP Banks.

A user can have access to several spaces. The API Explorer shows these under the Spaces menu.

In order to see the documentation for the Dynamic Endpoints and Dynamic Entities, a user may need to have access to the CanReadDynamicResourceDocsAtOneBank Role.

You can create your own Space by creating an OBP Bank.

Static Endpoint

Static endpoints are served from static Scala source code which is contained in (public) Git repositories.

Static endpoints cover all the OBP API and User management functionality as well as the Open Bank Project banking APIs and other Open Banking standards such as UK Open Banking, Berlin Group and STET etc..
In short, Static (standard) endpoints are defined in Git as Scala source code, where as Dynamic (custom) endpoints are defined in the OBP database.

Modifications to Static endpoint core properties such as URLs and response bodies require source code changes and an instance restart. However, JSON Schema Validation and Dynamic Connector changes can be applied in real-time.

Template.attributeName

Example value: SPECIAL_TAX_NUMBER

Description: Attribute name

Template.attributeType

Example value: STRING

Description: Attribute type.

Transaction

Transactions are records of successful movements of value into or out of an Account.

OBP Transactions don't contain any "draft" or "pending" Transactions; pending transactions see represented by Transaction Requests.

OBP Transactions are modelled on a Bank statement where everything is based on the perspective of my account.
That is, if I look at "my account", I see credits (positive numbers) and debits (negative numbers)

An OBP transaction stores information including the:
Bank ID
Account ID
Currency
Amount (positive for a credit, negative for a debit)
Date
Counterparty (information that describes the other party in the transaction)
- optionally description and new balance.

Note, OBP operates a Double-Entry Bookkeeping system which means that every transfer of value within OBP is represented by two transactions.

For instance, to represent 5 Euros going from Account A to Account B, we would have 2 transactions:

Transaction 1.

Account: A
Currency: EUR
Amount: -5
Counterparty: Account B

Transaction 2.

Account: B
Currency: EUR
Amount: +5
Counterparty: Account A

The sum of the two transactions must be zero.

What about representing value coming into or out of the system? Here we use "settlement accounts":

OBP-INCOMING-SETTLEMENT-ACCOUNT is typically the ID for a default incoming settlement account

OBP-OUTGOING-SETTLEMENT-ACCOUNT is typically the ID for a default outgoing settlement account

See the following diagram:

OBP Double-Entry Bookkeeping

See the Get Double Entry Transaction endpoint

Go Back to Transaction APIs

Transaction Requests

Transaction Requests are records of transaction / payment requests coming to the API. They may or may not result in Transactions (following authorisation, security challenges and sufficient funds etc.)

A successful Transaction Request results in a Transaction.

For more information see here

Transaction Requests.Transaction Request Refund Reason Code

Example value: CUST

Description: Defines the reason code of a transaction refund request (e.g. a SEPA Credit Transfer Scheme reason code).

Transaction Requests.Transaction Request Type

Example value: SEPA

Description: The Transaction Request Type defines the request body that is required - and the logic / flow of the Transaction Request. Allowed values include SEPA, COUNTERPARTY and SANDBOX_TAN.

Transaction Requests.attributeId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: Transaction Request attribute id

Transaction Requests.attributeName

Example value: HOUSE_RENT

Description: Transaction Request attribute name

Transaction Requests.attributeType

Example value: DATE_WITH_DAY

Description: Transaction Request attribute type.

Transaction Requests.attributeValue

Example value: 123456789

Description: Transaction Request attribute value.

Transaction Requests.id

Example value: 8138a7e4-6d02-40e3-a129-0b2bf89de9f1

Description: The Transaction Request Id

Transaction.attributeId

Example value: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

Description: Transaction attribute id

Transaction.attributeName

Example value: HOUSE_RENT

Description: Transaction attribute name

Transaction.attributeType

Example value: DATE_WITH_DAY

Description: Transaction attribute type.

Transaction.attributeValue

Example value: 123456789

Description: Transaction attribute value.

Transaction.charge_policy

Example value: SHARED

Description: The transaction fee charge policy, can be shared, debit account or credit account.

Transaction.otherAccountProvider

Example value:

Description:

Transaction.transactionDescription

Example value: The piano lession-Invoice No:68

Description: A description or reference for the transaction

Transaction.transactionId

Example value: 2fg8a7e4-6d02-40e3-a129-0b2bf89de8ub

Description: The Transaction ID used in URLs. Used to store Metadata for the Transaction.

Transaction.transactionType

Example value: DEBIT

Description: A code for the type of transaction

User

The entity that accesses the API with a login / authorisation token and has access to zero or more resources on the OBP API. The User is linked to the core banking user / customer at the South Side Adapter layer.

Go Back to User APIs

Link Users and Customers in a many to many relationship. A User can represent many Customers (e.g. the bank may have several Customer records for the same individual or a dependant). In this way Customers can easily be attached / detached from Users.

User.attributeName

Example value: BATTERY_LEVEL

Description: User attribute name

User.attributeType

Example value: STRING

Description: User attribute type.

User.attributeValue

Example value: 90

Description: User attribute value.

User.isPersonal

Example value: false

Description: User attribute is personal value.

User.password

Example value: password

Description: The password the user uses to authenticate.

User.provider

The name of the authentication service. e.g. the OBP hostname or kafka if users are authenticated over Kafka.

User.provider_id

The id of the user given by the authentication provider.

User.userId

Example value: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

Description: A string that MUST uniquely identify the user on this OBP instance.

User.userNameExample

Example value: felixsmith

Description: The userName the user uses to authenticate.

User.user_id

An identifier that MUST NOT leak the user name or other identifier nomrally used by the customer or bank staff. It SHOULD be a UUID and MUST be unique on the OBP instance.

Example value: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

User.username

Example value: felixsmith

Description: The username the user uses to authenticate.

accessibility_features

Example value: ["ATAC","ATAD"]

Description: no-description-provided

accessiblefeatures

Example value:

Description: no-description-provided

account

Example value:

Description: no-description-provided

account_application_id

Example value:

Description: no-description-provided

account_applications

Example value:

Description: no-description-provided

account_attribute_id

Example value:

Description: no-description-provided

account_attributes

Example value:

Description: no-description-provided

account_otp

Example value:

Description: no-description-provided

account_routing

Example value:

Description: no-description-provided

account_routings

Example value:

Description: no-description-provided

account_rules

Example value:

Description: no-description-provided

account_webhook_id

Example value:

Description: no-description-provided

accounts

Example value:

Description: no-description-provided

active

Example value: true

Description: no-description-provided

actual_date

Example value: 2020-01-27

Description: no-description-provided

adapter_implementation

Example value:

Description: no-description-provided

address

Example value:

Description: no-description-provided

addresses

Example value:

Description: no-description-provided

age

Example value: 18

Description: The user age.

akka

Example value:

Description: no-description-provided

alias

Example value:

Description: no-description-provided

allowed_actions

Example value:

Description: no-description-provided

allowed_attempts

Example value: 5

Description: no-description-provided

allows

Example value: [credit,debit,cash_withdrawal]

Description: The actions of the card.

answer

Example value:

Description: no-description-provided

api_version

Example value:

Description: no-description-provided

app_name

Example value:

Description: no-description-provided

app_type

Example value:

Description: no-description-provided

atm_id

Example value: atme-9a0f-4bfa-b30b-9003aa467f51

Description: A string that MUST uniquely identify the ATM on this OBP instance.

atms

Example value:

Description: no-description-provided

attribute_definition_id

Example value:

Description: no-description-provided

attribute_id

Example value:

Description: no-description-provided

attributes

Example value: attribute value in form of (name, value)

Description: no-description-provided

auth_context_update_id

Example value:

Description: no-description-provided

available_funds_request_id

Example value:

Description: no-description-provided

average_response_time

Example value:

Description: no-description-provided

bad_attempts_since_last_success_or_reset

Example value:

Description: no-description-provided

balance

Example value: 10

Description: no-description-provided

bank

Example value:

Description: no-description-provided

bank_code

Example value: CGHZ

Description: no-description-provided

bank_id_pattern

Example value:

Description: no-description-provided

bank_routing

Example value:

Description: no-description-provided

bank_routings

Example value: bank routing in form of (scheme, address)

Description: no-description-provided

bankid

Example value:

Description: no-description-provided

banks

Example value:

Description: no-description-provided

bespoke

Example value:

Description: no-description-provided

bic

Example value: BUKBGB22

Description: The Business Identifier Code

branch_number

Example value:

Description: no-description-provided

branch_routing

Example value:

Description: no-description-provided

branch_routings

Example value:

Description: no-description-provided

branch_type

Example value:

Description: no-description-provided

branches

Example value:

Description: no-description-provided

cache

Example value:

Description: no-description-provided

calls_made

Example value: 50

Description: no-description-provided

can_add_comment

Example value:

Description: no-description-provided

can_add_corporate_location

Example value:

Description: no-description-provided

can_add_counterparty

Example value: true

Description: no-description-provided

can_add_image

Example value:

Description: no-description-provided

can_add_image_url

Example value: true

Description: no-description-provided

can_add_more_info

Example value: true

Description: no-description-provided

can_add_open_corporates_url

Example value:

Description: no-description-provided

can_add_physical_location

Example value:

Description: no-description-provided

can_add_private_alias

Example value:

Description: no-description-provided

can_add_public_alias

Example value:

Description: no-description-provided

can_add_tag

Example value: true

Description: no-description-provided

can_add_transaction_request_to_any_account

Example value:

Description: no-description-provided

can_add_transaction_request_to_own_account

Example value:

Description: no-description-provided

can_add_url

Example value:

Description: no-description-provided

can_add_where_tag

Example value:

Description: no-description-provided

can_be_seen_on_views

Example value: true

Description: no-description-provided

can_create_direct_debit

Example value: true

Description: no-description-provided

can_create_standing_order

Example value:

Description: no-description-provided

can_delete_comment

Example value:

Description: no-description-provided

can_delete_corporate_location

Example value: true

Description: no-description-provided

can_delete_image

Example value: true

Description: no-description-provided

can_delete_physical_location

Example value:

Description: no-description-provided

can_delete_tag

Example value:

Description: no-description-provided

can_delete_where_tag

Example value: true

Description: no-description-provided

can_edit_owner_comment

Example value: true

Description: no-description-provided

can_query_available_funds

Example value: true

Description: no-description-provided

can_see_bank_account_balance

Example value:

Description: no-description-provided

can_see_bank_account_bank_name

Example value: true

Description: no-description-provided

can_see_bank_account_credit_limit

Example value: true

Description: no-description-provided

can_see_bank_account_currency

Example value:

Description: no-description-provided

can_see_bank_account_iban

Example value:

Description: no-description-provided

can_see_bank_account_label

Example value: true

Description: no-description-provided

can_see_bank_account_national_identifier

Example value:

Description: no-description-provided

can_see_bank_account_number

Example value: true

Description: no-description-provided

can_see_bank_account_owners

Example value: true

Description: no-description-provided

can_see_bank_account_routing_address

Example value:

Description: no-description-provided

can_see_bank_account_routing_scheme

Example value:

Description: no-description-provided

can_see_bank_account_swift_bic

Example value:

Description: no-description-provided

can_see_bank_account_type

Example value:

Description: no-description-provided

can_see_bank_routing_address

Example value: true

Description: no-description-provided

can_see_bank_routing_scheme

Example value:

Description: no-description-provided

can_see_comments

Example value:

Description: no-description-provided

can_see_corporate_location

Example value: true

Description: no-description-provided

can_see_image_url

Example value: true

Description: no-description-provided

can_see_images

Example value: true

Description: no-description-provided

can_see_more_info

Example value:

Description: no-description-provided

can_see_open_corporates_url

Example value:

Description: no-description-provided

can_see_other_account_bank_name

Example value:

Description: no-description-provided

can_see_other_account_iban

Example value:

Description: no-description-provided

can_see_other_account_kind

Example value:

Description: no-description-provided

can_see_other_account_metadata

Example value:

Description: no-description-provided

can_see_other_account_national_identifier

Example value: true

Description: no-description-provided

can_see_other_account_number

Example value: true

Description: no-description-provided

can_see_other_account_routing_address

Example value: true

Description: no-description-provided

can_see_other_account_routing_scheme

Example value:

Description: no-description-provided

can_see_other_account_swift_bic

Example value: true

Description: no-description-provided

can_see_other_bank_routing_address

Example value:

Description: no-description-provided

can_see_other_bank_routing_scheme

Example value:

Description: no-description-provided

can_see_owner_comment

Example value:

Description: no-description-provided

can_see_physical_location

Example value:

Description: no-description-provided

can_see_private_alias

Example value:

Description: no-description-provided

can_see_public_alias

Example value:

Description: no-description-provided

can_see_tags

Example value:

Description: no-description-provided

can_see_transaction_amount

Example value: true

Description: no-description-provided

can_see_transaction_balance

Example value:

Description: no-description-provided

can_see_transaction_currency

Example value:

Description: no-description-provided

can_see_transaction_description

Example value: true

Description: no-description-provided

can_see_transaction_finish_date

Example value:

Description: no-description-provided

can_see_transaction_metadata

Example value:

Description: no-description-provided

can_see_transaction_other_bank_account

Example value:

Description: no-description-provided

can_see_transaction_start_date

Example value:

Description: no-description-provided

can_see_transaction_this_bank_account

Example value:

Description: no-description-provided

can_see_transaction_type

Example value:

Description: no-description-provided

can_see_url

Example value: true

Description: no-description-provided

can_see_where_tag

Example value: true

Description: no-description-provided

cancelled

Example value: true

Description: no-description-provided

card_attributes

Example value:

Description: no-description-provided

card_description

Example value:

Description: no-description-provided

cards

Example value:

Description: no-description-provided

category

Example value:

Description: no-description-provided

challenge

Example value:

Description: no-description-provided

challenge_type

Example value:

Description: no-description-provided

channel

Example value:

Description: no-description-provided

charge

Example value:

Description: no-description-provided

checks

Example value:

Description: no-description-provided

city

Example value:

Description: no-description-provided

closing_time

Example value: 2020-01-27

Description: no-description-provided

code

Example value: 125

Description: no-description-provided

collected

Example value: 2020-01-27

Description: no-description-provided

collection_code

Example value:

Description: no-description-provided

comment_id

Example value:

Description: no-description-provided

comments

Example value:

Description: no-description-provided

company

Example value: Tesobe GmbH

Description: The company name

completed

Example value: 2020-01-27

Description: no-description-provided

connector_name

Example value:

Description: no-description-provided

connector_version

Example value:

Description: no-description-provided

Example value:

Description: no-description-provided

Example value: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

Description: A string that MUST uniquely identify the Consent Request on this OBP instance.

consents

Example value:

Description: no-description-provided

consumers

Example value:

Description: no-description-provided

contact_details

Example value:

Description: no-description-provided

conversion_value

Example value: 100

Description: no-description-provided

corporate_location

Example value: 10

Description: no-description-provided

count

Example value:

Description: no-description-provided

counterparties

Example value:

Description: no-description-provided

counterparty

Example value:

Description: no-description-provided

country

Example value: Germany

Description: The country name

country_code

Example value: 1254

Description: no-description-provided

county

Example value:

Description: no-description-provided

created

Example value:

Description: no-description-provided

created_by_user

Example value:

Description: no-description-provided

created_by_user_id

Example value:

Description: no-description-provided

creator

Example value:

Description: no-description-provided

credit_limit

Example value:

Description: no-description-provided

credit_rating

Example value:

Description: no-description-provided

creditoraccount

Example value:

Description: no-description-provided

creditorname

Example value:

Description: no-description-provided

crm_events

Example value:

Description: no-description-provided

current_credit_documentation

Example value:

Description: no-description-provided

current_state

Example value:

Description: no-description-provided

customer

Example value:

Description: no-description-provided

customer_address_id

Example value:

Description: no-description-provided

customer_attributes

Example value:

Description: no-description-provided

customer_name

Example value:

Description: no-description-provided

customer_token

Example value:

Description: no-description-provided

customer_user_id

Example value:

Description: no-description-provided

customers

Example value:

Description: no-description-provided

data.bankid

Example value:

Description: no-description-provided

date_activated

Example value:

Description: no-description-provided

date_added

Example value:

Description: no-description-provided

date_inserted

Example value:

Description: no-description-provided

date_of_application

Example value: 2020-01-27

Description: no-description-provided

debtoraccount

Example value:

Description: no-description-provided

dependent_endpoints

Example value:

Description: no-description-provided

description

Example value: This an optional field. Maximum length is 2000. It can be any characters here.

Description: The human readable description here.

detail

Example value:

Description: no-description-provided

details

Example value:

Description: no-description-provided

developer_email

Example value:

Description: no-description-provided

direct_debit_id

Example value:

Description: no-description-provided

display_name

Example value:

Description: no-description-provided

distribution_channel

Example value:

Description: no-description-provided

dob_of_dependants

Example value: [2019-09-08, 2017-07-12]

Description: no-description-provided

document_number

Example value:

Description: no-description-provided

documents

Example value:

Description: no-description-provided

domain

Example value:

Description: no-description-provided

drive_up

Example value:

Description: no-description-provided

driveup

Example value:

Description: no-description-provided

duration

Example value: 5.123

Description: This is a decimal number in seconds, eg: 1 for 1 second, 0.001 for 1 ms

duration_time

Example value: 60

Description: no-description-provided

e

Example value:

Description: no-description-provided

effective_date

Example value: 2020-01-27

Description: no-description-provided

Example value:

Description: no-description-provided

email_address

Example value:

Description: no-description-provided

enabled

Example value: true

Description: no-description-provided

end_date

Example value:

Description: no-description-provided

energy_source

Example value:

Description: no-description-provided

entitlement_id

Example value:

Description: no-description-provided

entitlement_request_id

Example value:

Description: no-description-provided

entitlement_requests

Example value:

Description: no-description-provided

entitlements

Example value:

Description: no-description-provided

errorCode

Example value:

Description: no-description-provided

everything

Example value:

Description: no-description-provided

example_inbound_message

Example value: {}

Description: This is the json object.

example_outbound_message

Example value: {}

Description: this will the json object

execution_date

Example value: 2020-01-27

Description: no-description-provided

execution_time

Example value:

Description: no-description-provided

face_image

Example value:

Description: no-description-provided

family

Example value:

Description: no-description-provided

field

Example value:

Description: no-description-provided

first_check_number

Example value:

Description: no-description-provided

first_name

Example value: Tom

Description: The first name

free_form

Example value:

Description: no-description-provided

frequency

Example value: DAILY

Description: no-description-provided

friday

Example value:

Description: no-description-provided

from

Example value:

Description: no-description-provided

from_currency_code

Example value:

Description: no-description-provided

from_date

Example value:

Description: no-description-provided

from_department

Example value: Open Bank

Description: The department of the sender

from_person

Example value: Tom

Description: The name of the sender

full_name

Example value: full name string

Description: no-description-provided

function_name

Example value:

Description: no-description-provided

future_date

Example value: 20200127

Description: no-description-provided

generate_accountants_view

Example value:

Description: no-description-provided

generate_auditors_view

Example value:

Description: no-description-provided

generate_public_view

Example value:

Description: no-description-provided

glossary_items

Example value:

Description: no-description-provided

group

Example value:

Description: no-description-provided

handle

Example value:

Description: no-description-provided

hide_metadata_if_alias_used

Example value:

Description: no-description-provided

holder

Example value:

Description: no-description-provided

holders

Example value:

Description: no-description-provided

hosted_at

Example value:

Description: no-description-provided

hosted_by

Example value:

Description: no-description-provided

hours

Example value:

Description: no-description-provided

how

Example value:

Description: no-description-provided

html

Example value: html format content

Description: the content is displayed in HTML format

http_method

Example value: GET

Description: no-description-provided

http_protocol

Example value:

Description: no-description-provided

id

Example value: d8839721-ad8f-45dd-9f78-2080414b93f9

Description: no-description-provided

id

Example value: 5995d6a2-01b3-423c-a173-5481df49bdaf

Description: A string that, in combination with the bankId MUST uniquely identify the customer message on this OBP instance

image_id

Example value:

Description: no-description-provided

image_url

Example value:

Description: no-description-provided

images

Example value:

Description: no-description-provided

implemented_by_partial_function

Example value:

Description: no-description-provided

implemented_in_version

Example value:

Description: no-description-provided

inbound_topic

Example value:

Description: no-description-provided

inboundavroschema

Example value:

Description: no-description-provided

index

Example value:

Description: no-description-provided

instructedamount

Example value: 100

Description: no-description-provided

inverse_conversion_value

Example value: 50

Description: no-description-provided

invitees

Example value:

Description: no-description-provided

is_active

Example value: true

Description: no-description-provided

is_alias

Example value:

Description: no-description-provided

is_bank_id_exact_match

Example value: true

Description: no-description-provided

is_firehose

Example value:

Description: no-description-provided

is_public

Example value: true

Description: no-description-provided

issue_place

Example value:

Description: no-description-provided

items

Example value:

Description: no-description-provided

jsonstring

Example value:

Description: no-description-provided

jwks_uri

Example value:

Description: no-description-provided

jwks_uris

Example value:

Description: no-description-provided

jwt

Example value:

Description: no-description-provided

keys

Example value:

Description: no-description-provided

kid

Example value:

Description: no-description-provided

kind

Example value:

Description: no-description-provided

kty

Example value:

Description: no-description-provided

kyc_check_id

Example value:

Description: no-description-provided

kyc_document

Example value:

Description: no-description-provided

kyc_document_id

Example value:

Description: no-description-provided

kyc_media_id

Example value:

Description: no-description-provided

last_failure_date

Example value: 2020-01-27

Description: no-description-provided

last_lock_date

Example value: 2020-01-27

Description: no-description-provided

last_name

Example value: Smith

Description: The Last name

last_ok_date

Example value: 2023-03-18T21:00:27.872Z

Description: no-description-provided

latitude

Example value: 38.8951

Description: no-description-provided

license

Example value:

Description: no-description-provided

line1

Example value:

Description: no-description-provided

line2

Example value:

Description: no-description-provided

line3

Example value:

Description: no-description-provided

Example value:

Description: no-description-provided

list

Example value:

Description: no-description-provided

lobby

Example value:

Description: no-description-provided

location

Example value:

Description: no-description-provided

log_level

Example value:

Description: no-description-provided

Example value: logo url

Description: no-description-provided

longitude

Example value: -77.0364

Description: no-description-provided

markdown

Example value:

Description: no-description-provided

match_all

Example value:

Description: no-description-provided

maximum_response_time

Example value: 60

Description: no-description-provided

medias

Example value:

Description: no-description-provided

meeting_id

Example value:

Description: no-description-provided

meetings

Example value:

Description: no-description-provided

member_product_code

Example value:

Description: no-description-provided

message

Example value: 123456

Description: The messsage content to send to customer.

message_docs

Example value:

Description: no-description-provided

message_format

Example value:

Description: no-description-provided

messages

Example value:

Description: no-description-provided

meta

Example value:

Description: no-description-provided

metadata

Example value:

Description: no-description-provided

metadata_view

Example value:

Description: no-description-provided

method_name

Example value:

Description: no-description-provided

method_routing_id

Example value:

Description: no-description-provided

method_routings

Example value:

Description: no-description-provided

metrics

Example value:

Description: no-description-provided

minimum_response_time

Example value:

Description: no-description-provided

mobile_phone

Example value:

Description: no-description-provided

mobile_phone_number

Example value: +49 30 901820

Description: no-description-provided

monday

Example value:

Description: no-description-provided

more_info

Example value: More information about this fee

Description: no-description-provided

more_info_url

Example value: www.example.com/abc

Description: no-description-provided

n

Example value:

Description: no-description-provided

name

Example value: ACCOUNT_MANAGEMENT_FEE

Description: no-description-provided

narrative

Example value:

Description: no-description-provided

national_identifier

Example value:

Description: no-description-provided

networks

Example value:

Description: no-description-provided

new_balance

Example value: 20

Description: no-description-provided

nickname

Example value:

Description: no-description-provided

nominal_interest1

Example value:

Description: no-description-provided

nominal_interest2

Example value:

Description: no-description-provided

none

Example value:

Description: no-description-provided

number

Example value:

Description: no-description-provided

number_of_checkbooks

Example value:

Description: no-description-provided

ok

Example value: true

Description: no-description-provided

on_hot_list

Example value: false

Description: no-description-provided

open_corporates_url

Example value:

Description: no-description-provided

opening_time

Example value:

Description: no-description-provided

order

Example value:

Description: no-description-provided

order_date

Example value: 2020-01-27

Description: no-description-provided

order_id

Example value:

Description: no-description-provided

orders

Example value:

Description: no-description-provided

organisation

Example value:

Description: no-description-provided

organisation_website

Example value:

Description: no-description-provided

other_account

Example value:

Description: no-description-provided

other_account_id

Example value:

Description: no-description-provided

other_account_routing_address

Example value:

Description: no-description-provided

other_account_routing_scheme

Example value:

Description: no-description-provided

other_account_secondary_routing_address

Example value:

Description: no-description-provided

other_account_secondary_routing_scheme

Example value:

Description: no-description-provided

other_accounts

Example value:

Description: no-description-provided

other_bank_routing_address

Example value:

Description: no-description-provided

other_bank_routing_scheme

Example value:

Description: no-description-provided

other_branch_routing_address

Example value:

Description: no-description-provided

other_branch_routing_scheme

Example value:

Description: no-description-provided

outbound_topic

Example value:

Description: no-description-provided

outboundavroschema

Example value:

Description: no-description-provided

overall_balance

Example value: 10

Description: no-description-provided

overall_balance_date

Example value: 2020-01-27

Description: no-description-provided

owners

Example value:

Description: no-description-provided

parameters

Example value:

Description: no-description-provided

parent_product

Example value:

Description: no-description-provided

parent_product_code

Example value: 787LOW

Description: no-description-provided

payload

Example value: {
"everything": false,
"account_access": [
{
"account_routing": {
"scheme": "AccountNumber",
"address": "4930396"
},
"view_id": "owner"
}
],
"phone_number": "+44 07972 444 876",
"valid_from": "2022-06-14T12:42:00Z",
"time_to_live": 3600
}

Description: The whole create consent request json body.

per_day

Example value: 4000

Description: no-description-provided

per_day_call_limit

Example value:

Description: no-description-provided

per_hour

Example value:

Description: no-description-provided

per_hour_call_limit

Example value:

Description: no-description-provided

per_minute

Example value:

Description: no-description-provided

per_minute_call_limit

Example value:

Description: no-description-provided

per_month

Example value: 500

Description: no-description-provided

per_month_call_limit

Example value:

Description: no-description-provided

per_second

Example value: 1000

Description: no-description-provided

per_second_call_limit

Example value: 10

Description: no-description-provided

per_week

Example value: 50000

Description: no-description-provided

per_week_call_limit

Example value:

Description: no-description-provided

permissions

Example value:

Description: no-description-provided

phone

Example value:

Description: no-description-provided

phone_number

Example value:

Description: no-description-provided

physical_location

Example value:

Description: no-description-provided

pin_reset

Example value:

Description: no-description-provided

ports

Example value:

Description: no-description-provided

post_code

Example value: 789

Description: no-description-provided

postcode

Example value:

Description: no-description-provided

posted

Example value: 2020-01-27

Description: no-description-provided

present

Example value:

Description: no-description-provided

private_alias

Example value:

Description: no-description-provided

process

Example value: obp.getBank

Description: The format must be obp.xxxx, 'obp.' is the prefix, xxx will be the connector method name

product_attribute_id

Example value:

Description: no-description-provided

product_attributes

Example value:

Description: no-description-provided

product_code

Example value: 1234BW

Description: no-description-provided

product_collection

Example value:

Description: no-description-provided

product_fee_id

Example value: 696hlAHLFKUHE37469287634

Description: no-description-provided

product_name

Example value: Deposit Account 1

Description: no-description-provided

products

Example value:

Description: no-description-provided

property

Example value:

Description: no-description-provided

provider

Example value: ETHEREUM

Description: the provider name

provider_id

Example value:

Description: no-description-provided

public_alias

Example value:

Description: no-description-provided

purpose

Example value: DEVELOPER

Description: no-description-provided

purpose_id

Example value:

Description: no-description-provided

query

Example value:

Description: no-description-provided

rank_amount1

Example value: 100

Description: no-description-provided

rank_amount2

Example value:

Description: no-description-provided

reason_requested

Example value:

Description: no-description-provided

reasons

Example value:

Description: no-description-provided

redirect_url

Example value:

Description: no-description-provided

relates_to_kyc_check_id

Example value:

Description: no-description-provided

relates_to_kyc_document_id

Example value:

Description: no-description-provided

remote_data_secret_matched

Example value:

Description: no-description-provided

replacement

Example value:

Description: no-description-provided

request_id

Example value:

Description: no-description-provided

requested_current_rate_amount1

Example value:

Description: no-description-provided

requested_current_rate_amount2

Example value: 20

Description: no-description-provided

requested_current_valid_end_date

Example value:

Description: no-description-provided

requested_temporary_valid_end_date

Example value:

Description: no-description-provided

require_scopes_for_all_roles

Example value:

Description: no-description-provided

require_scopes_for_listed_roles

Example value: true

Description: no-description-provided

requiredfieldinfo

Example value: false

Description: no-description-provided

requires_bank_id

Example value:

Description: no-description-provided

reset_in_seconds

Example value:

Description: no-description-provided

reset_password_url

Example value:

Description: no-description-provided

result

Example value:

Description: no-description-provided

revoked

Example value:

Description: no-description-provided

role

Example value:

Description: no-description-provided

role_name

Example value:

Description: no-description-provided

roles

Example value: CanCreateMyUser

Description: Entitlements are used to grant System or Bank level roles to Users

sandbox_tan

Example value:

Description: no-description-provided

satisfied

Example value: true

Description: no-description-provided

saturday

Example value:

Description: no-description-provided

sca_method

Example value:

Description: no-description-provided

scheduled_date

Example value: 2020-01-27

Description: no-description-provided

scheme

Example value: scheme value

Description: no-description-provided

scope_id

Example value:

Description: no-description-provided

scopes

Example value:

Description: no-description-provided

sepa

Example value:

Description: no-description-provided

sepaB2b

Example value: yes

Description: no-description-provided

sepaCardClearing

Example value: no

Description: no-description-provided

sepaCreditTransfer

Example value: yes

Description: no-description-provided

sepaDirectDebit

Example value: yes

Description: no-description-provided

sepaSddCore

Example value: yes

Description: no-description-provided

service_available

Example value:

Description: no-description-provided

settlement_accounts

Example value:

Description: no-description-provided

shipping_code

Example value:

Description: no-description-provided

short_code

Example value:

Description: no-description-provided

short_name

Example value:

Description: no-description-provided

short_reference

Example value:

Description: no-description-provided

shortcode

Example value:

Description: no-description-provided

sms

Example value:

Description: no-description-provided

staff_name

Example value:

Description: no-description-provided

staff_token

Example value:

Description: no-description-provided

staff_user_id

Example value:

Description: no-description-provided

standing_order_id

Example value:

Description: no-description-provided

state

Example value:

Description: no-description-provided

status

Example value:

Description: no-description-provided

statuses

Example value:

Description: no-description-provided

success

Example value:

Description: no-description-provided

suggested_order

Example value:

Description: no-description-provided

summary

Example value:

Description: no-description-provided

sunday

Example value:

Description: no-description-provided

super_family

Example value:

Description: no-description-provided

supported_currencies

Example value: ["EUR","MXN","USD"]

Description: no-description-provided

supported_languages

Example value: ["EUR","MXN","USD"]

Description: no-description-provided

swift_bic

Example value:

Description: no-description-provided

tag_id

Example value:

Description: no-description-provided

tags

Example value: Create-My-User

Description: OBP uses the tags to group the endpoints, the relevant endpoints can share the same tag.

tax_number

Example value: 456

Description: no-description-provided

tax_residence

Example value:

Description: no-description-provided

tax_residence_id

Example value:

Description: no-description-provided

technology

Example value: technology1

Description: no-description-provided

temporary_credit_documentation

Example value:

Description: no-description-provided

temporary_requested_current_amount

Example value:

Description: no-description-provided

terms_and_conditions_url_example

Example value: www.example.com/xyz

Description: no-description-provided

text

Example value:

Description: no-description-provided

this_account

Example value:

Description: no-description-provided

this_account_id

Example value:

Description: no-description-provided

this_bank_id

Example value:

Description: no-description-provided

this_view_id

Example value:

Description: no-description-provided

thursday

Example value:

Description: no-description-provided

time_to_live

Example value:

Description: no-description-provided

to

Example value:

Description: no-description-provided

to_counterparty

Example value:

Description: no-description-provided

to_currency_code

Example value: EUR

Description: no-description-provided

to_date

Example value:

Description: no-description-provided

to_sandbox_tan

Example value:

Description: no-description-provided

to_sepa

Example value:

Description: no-description-provided

to_sepa_credit_transfers

Example value:

Description: no-description-provided

to_transfer_to_account

Example value:

Description: no-description-provided

to_transfer_to_atm

Example value:

Description: no-description-provided

to_transfer_to_phone

Example value:

Description: no-description-provided

token

Example value:

Description: no-description-provided

top_apis

Example value:

Description: no-description-provided

top_consumers

Example value:

Description: no-description-provided

transaction_attributes

Example value:

Description: no-description-provided

transaction_ids

Example value:

Description: no-description-provided

transaction_request_types

Example value:

Description: no-description-provided

transaction_requests_with_charges

Example value:

Description: no-description-provided

transaction_types

Example value:

Description: no-description-provided

transactions

Example value:

Description: no-description-provided

transfer_type

Example value:

Description: no-description-provided

transport

Example value: SMS

Description: It can be SMS or Email or other transport types

trigger_name

Example value:

Description: no-description-provided

ttl_in_seconds

Example value:

Description: no-description-provided

tuesday

Example value:

Description: no-description-provided

type

Example value:

Description: no-description-provided

type_of_lock

Example value:

Description: no-description-provided

use

Example value:

Description: no-description-provided

use_type

Example value:

Description: no-description-provided

user

Example value:

Description: no-description-provided

user_auth_context_id

Example value:

Description: no-description-provided

user_auth_context_update_id

Example value:

Description: no-description-provided

user_auth_contexts

Example value:

Description: no-description-provided

Example value:

Description: no-description-provided

Example value:

Description: no-description-provided

users

Example value: user list

Description: Please refer to the user object.

valid_from

Example value: 2020-01-27

Description: no-description-provided

verb

Example value:

Description: no-description-provided

version

Example value:

Description: no-description-provided

version_status

Example value:

Description: no-description-provided

view

Example value:

Description: no-description-provided

view.description

Example value: This view is for the owner for the account.

Description: A description for this view.

view.id

Example value: owner

Description: A viewId can be owner, accountant, public ....

view.is_system

Example value: true

Description: If the view is the system level, then it is true

view.name

Example value: Owner

Description: A viewName can be Owner, Accountant, Public ....

views

Example value:

Description: no-description-provided

views_available

Example value:

Description: no-description-provided

views_basic

Example value:

Description: no-description-provided

warehouse

Example value:

Description: no-description-provided

web_hooks

Example value:

Description: no-description-provided

web_ui_props_id

Example value:

Description: no-description-provided

website

Example value: www.openbankproject.com

Description: no-description-provided

webui_props

Example value:

Description: no-description-provided

wednesday

Example value:

Description: no-description-provided

when

Example value: 2020-01-27

Description: no-description-provided

where

Example value:

Description: no-description-provided

which_alias_to_use

Example value:

Description: no-description-provided