right logo image
right logo image
Log on
⯆

API Explorer

v5.1.0 (11 APIs)

API Host: https://obp-apisandbox.joinfincubator.com
Bank
Accounts
Views
Counterparties
Transactions

Create Account (PUT)

Create Account at bank specified by BANK_ID with Id specified by ACCOUNT_ID.

The User can create an Account for themself - or - the User that has the USER_ID specified in the POST body.

If the PUT body USER_ID is specified, the logged in user must have the Role canCreateAccount. Once created, the Account will be owned by the User specified by USER_ID.

If the PUT body USER_ID is not specified, the account will be owned by the logged in User.

The 'product_code' field SHOULD be a product_code from Product.
If the 'product_code' matches a product_code from Product, account attributes will be created that match the Product Attributes.

Note: The Amount MUST be zero.

Authentication is Mandatory

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON response body fields:

account_attribute_id:

account_attributes:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

account_routings:

address:

amount: 10.12

balance: 10

branch_id: DERBY6

currency: EUR

label: My Account

name: ACCOUNT_MANAGEMENT_FEE

product_code: 1234BW

scheme: scheme value

type:

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

value: 5987953

product_instance_code: product_instance_code

Typical Successful Response: 

								
									
{
  "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
  "user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
  "label":"My Account",
  "product_code":"1234BW",
  "balance":{
    "currency":"EUR",
    "amount":"0"
  },
  "branch_id":"DERBY6",
  "account_routings":[{
    "scheme":"AccountNumber",
    "address":"4930396"
  }],
  "account_attributes":[{
    "product_code":"1234BW",
    "account_attribute_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f",
    "name":"OVERDRAFT_START_DATE",
    "type":"DATE_WITH_DAY",
    "value":"2012-04-23",
    "product_instance_code":"LKJL98769F"
  }]
}
Required Roles:
  • CanCreateAccount - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-10001: Incorrect json format.
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30107: Invalid User Id.
  • OBP-30110: Invalid Account Id. The ACCOUNT_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-30111: Invalid Bank Id. The BANK_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-20006: User is missing one or more roles:
  • OBP-30106: Invalid Balance Amount.
  • OBP-30112: Invalid Number. Initial balance must be a number, e.g 1000.00
  • OBP-30109: Initial Balance of Account must be Zero (0).
  • OBP-30105: Invalid Balance Currency.
  • OBP-30208: Account_ID already exists at the Bank.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createAccount, operation_id: OBPv5.0.0-createAccount Tags: Account, Onboarding,

Grant User access to View

Grants the User identified by USER_ID access to the view identified by VIEW_ID.

Authentication is Mandatory and the user needs to be account holder.

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

JSON request body fields:

is_system: true

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

view:

view_id: owner

JSON response body fields:

alias:

can_add_comment:

can_add_corporate_location:

can_add_counterparty: false

can_add_image:

can_add_image_url: false

can_add_more_info: false

can_add_open_corporates_url:

can_add_physical_location:

can_add_private_alias:

can_add_public_alias:

can_add_tag: false

can_add_transaction_request_to_any_account:

can_add_transaction_request_to_own_account:

can_add_url:

can_add_where_tag:

can_create_direct_debit: false

can_create_standing_order:

can_delete_comment:

can_delete_corporate_location: false

can_delete_image: false

can_delete_physical_location:

can_delete_tag:

can_delete_where_tag: false

can_edit_owner_comment: false

can_query_available_funds: false

can_see_bank_account_balance:

can_see_bank_account_bank_name: false

can_see_bank_account_credit_limit: false

can_see_bank_account_currency:

can_see_bank_account_iban:

can_see_bank_account_label: false

can_see_bank_account_national_identifier:

can_see_bank_account_number: false

can_see_bank_account_owners: false

can_see_bank_account_routing_address:

can_see_bank_account_routing_scheme:

can_see_bank_account_swift_bic:

can_see_bank_account_type:

can_see_bank_routing_address: false

can_see_bank_routing_scheme:

can_see_comments:

can_see_corporate_location: false

can_see_image_url: false

can_see_images: false

can_see_more_info:

can_see_open_corporates_url:

can_see_other_account_bank_name:

can_see_other_account_iban:

can_see_other_account_kind:

can_see_other_account_metadata:

can_see_other_account_national_identifier: false

can_see_other_account_number: false

can_see_other_account_routing_address: false

can_see_other_account_routing_scheme:

can_see_other_account_swift_bic: false

can_see_other_bank_routing_address:

can_see_other_bank_routing_scheme:

can_see_owner_comment:

can_see_physical_location:

can_see_private_alias:

can_see_public_alias:

can_see_tags:

can_see_transaction_amount: false

can_see_transaction_balance:

can_see_transaction_currency:

can_see_transaction_description: false

can_see_transaction_finish_date:

can_see_transaction_metadata:

can_see_transaction_other_bank_account:

can_see_transaction_start_date:

can_see_transaction_this_bank_account:

can_see_transaction_type:

can_see_url: false

can_see_where_tag: false

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

hide_metadata_if_alias_used: false

id: d8839721-ad8f-45dd-9f78-2080414b93f9

is_public: false

is_system: true

metadata_view:

short_name:

is_firehose:

Typical Successful Response: 

								
									
{
  "id":"1234",
  "short_name":"short_name",
  "description":"description",
  "metadata_view":"owner",
  "is_public":true,
  "is_system":true,
  "alias":"No",
  "hide_metadata_if_alias_used":true,
  "can_add_comment":true,
  "can_add_corporate_location":true,
  "can_add_image":true,
  "can_add_image_url":true,
  "can_add_more_info":true,
  "can_add_open_corporates_url":true,
  "can_add_physical_location":true,
  "can_add_private_alias":true,
  "can_add_public_alias":true,
  "can_add_tag":true,
  "can_add_url":true,
  "can_add_where_tag":true,
  "can_delete_comment":true,
  "can_add_counterparty":true,
  "can_delete_corporate_location":true,
  "can_delete_image":true,
  "can_delete_physical_location":true,
  "can_delete_tag":true,
  "can_delete_where_tag":true,
  "can_edit_owner_comment":true,
  "can_see_bank_account_balance":true,
  "can_query_available_funds":true,
  "can_see_bank_account_bank_name":true,
  "can_see_bank_account_currency":true,
  "can_see_bank_account_iban":true,
  "can_see_bank_account_label":true,
  "can_see_bank_account_national_identifier":true,
  "can_see_bank_account_number":true,
  "can_see_bank_account_owners":true,
  "can_see_bank_account_swift_bic":true,
  "can_see_bank_account_type":true,
  "can_see_comments":true,
  "can_see_corporate_location":true,
  "can_see_image_url":true,
  "can_see_images":true,
  "can_see_more_info":true,
  "can_see_open_corporates_url":true,
  "can_see_other_account_bank_name":true,
  "can_see_other_account_iban":true,
  "can_see_other_account_kind":true,
  "can_see_other_account_metadata":true,
  "can_see_other_account_national_identifier":true,
  "can_see_other_account_number":true,
  "can_see_other_account_swift_bic":true,
  "can_see_owner_comment":true,
  "can_see_physical_location":true,
  "can_see_private_alias":true,
  "can_see_public_alias":true,
  "can_see_tags":true,
  "can_see_transaction_amount":true,
  "can_see_transaction_balance":true,
  "can_see_transaction_currency":true,
  "can_see_transaction_description":true,
  "can_see_transaction_finish_date":true,
  "can_see_transaction_metadata":true,
  "can_see_transaction_other_bank_account":true,
  "can_see_transaction_start_date":true,
  "can_see_transaction_this_bank_account":true,
  "can_see_transaction_type":true,
  "can_see_url":true,
  "can_see_where_tag":true,
  "can_see_bank_routing_scheme":true,
  "can_see_bank_routing_address":true,
  "can_see_bank_account_routing_scheme":true,
  "can_see_bank_account_routing_address":true,
  "can_see_other_bank_routing_scheme":true,
  "can_see_other_bank_routing_address":true,
  "can_see_other_account_routing_scheme":true,
  "can_see_other_account_routing_address":true,
  "can_add_transaction_request_to_own_account":true,
  "can_add_transaction_request_to_any_account":true,
  "can_see_bank_account_credit_limit":true,
  "can_create_direct_debit":true,
  "can_create_standing_order":true
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20047: If target viewId is system view, the current view.can_grant_access_to_views does not contains it. Orif target viewId is custom view, the current view.can_grant_access_to_custom_views is false.
  • OBP-10001: Incorrect json format.
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-30252: System view not found. Please specify a valid value for VIEW_ID
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-30063: Cannot grant account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by grantUserAccessToView, operation_id: OBPv4.0.0-grantUserAccessToView Tags: Account-Access, View-Custom, Account, User, OwnerViewRequired,

Create Product

Create or Update Product for the Bank.

Typical Super Family values / Asset classes are:

Debt
Equity
FX
Commodity
Derivative

Product hiearchy vs Product Collections:

  • You can define a hierarchy of products - so that a child Product inherits attributes of its parent Product - using the parent_product_code in Product.

  • You can define a collection (also known as baskets or buckets) of products using Product Collections.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

PRODUCT_CODE: 1234BW

JSON response body fields:

bank_id: gh.29.uk

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

id: d8839721-ad8f-45dd-9f78-2080414b93f9

license:

meta:

more_info_url: www.example.com/abc

name: ACCOUNT_MANAGEMENT_FEE

parent_product_code: 787LOW

product_code: 1234BW

terms_and_conditions_url: www.example.com/xyz

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

fees: fees

Typical Successful Response: 

								
									
{
  "bank_id":"gh.29.uk",
  "product_code":"1234BW",
  "parent_product_code":"787LOW",
  "name":"Deposit Account 1",
  "more_info_url":"www.example.com/abc",
  "terms_and_conditions_url":"www.example.com/xyz",
  "description":"This an optional field. Maximum length is 2000. It can be any characters here.",
  "meta":{
    "license":{
      "id":"ODbL-1.0",
      "name":"Open Database License"
    }
  }
}
Required Roles:
  • CanCreateProduct - Please login to request this Role
  • CanCreateProductAtAnyBank - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-20006: User is missing one or more roles:
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createProduct, operation_id: OBPv5.0.0-createProduct Tags: Product,

Create Product Attribute

Create Product Attribute

Product Attributes are used to describe a financial Product with a list of typed key value pairs.

Each Product Attribute is linked to its Product by PRODUCT_CODE

Typical product attributes might be:

ISIN (for International bonds)
VKN (for German bonds)
REDCODE (markit short code for credit derivative)
LOAN_ID (e.g. used for Anacredit reporting)

ISSUE_DATE (When the bond was issued in the market)
MATURITY_DATE (End of life time of a product)
TRADABLE

See FPML for more examples.

The type field must be one of "STRING", "INTEGER", "DOUBLE" or DATE_WITH_DAY"

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

PRODUCT_CODE: 1234BW

JSON request body fields:

name: ACCOUNT_MANAGEMENT_FEE

type:

value: 5987953

is_active: false

JSON response body fields:

bank_id: gh.29.uk

name: ACCOUNT_MANAGEMENT_FEE

product_attribute_id:

product_code: 1234BW

type:

value: 5987953

is_active: false

Typical Successful Response: 

								
									
{
  "bank_id":"gh.29.uk",
  "product_code":"1234BW",
  "product_attribute_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f",
  "name":"OVERDRAFT_START_DATE",
  "type":"DATE_WITH_DAY",
  "value":"2012-04-23",
  "is_active":true
}
Required Roles:
  • CanCreateProductAttribute - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-10001: Incorrect json format.
  • OBP-50000: Unknown Error.
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by createProductAttribute, operation_id: OBPv4.0.0-createProductAttribute Tags: Product,

Create Product Fee

Create Product Fee

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

PRODUCT_CODE: 1234BW

JSON request body fields:

amount: 10.12

currency: EUR

frequency: DAILY

is_active: false

more_info: More information about this fee

name: ACCOUNT_MANAGEMENT_FEE

type:

value: 5987953

product_fee_id: 696hlAHLFKUHE37469287634

JSON response body fields:

amount: 10.12

bank_id: gh.29.uk

currency: EUR

frequency: DAILY

is_active: false

more_info: More information about this fee

name: ACCOUNT_MANAGEMENT_FEE

product_code: 1234BW

product_fee_id: 696hlAHLFKUHE37469287634

type:

value: 5987953

Typical Successful Response: 

								
									
{
  "bank_id":"gh.29.uk",
  "product_code":"1234BW",
  "product_fee_id":"696hlAHLFKUHE37469287634",
  "name":"ACCOUNT_MANAGEMENT_FEE",
  "is_active":true,
  "more_info":"More information about this fee",
  "value":{
    "currency":"EUR",
    "amount":"10.12",
    "frequency":"DAILY",
    "type":""
  }
}
Required Roles:
  • CanCreateProductFee - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-10001: Incorrect json format.
  • OBP-50000: Unknown Error.
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by createProductFee, operation_id: OBPv4.0.0-createProductFee Tags: Product,

Add Entitlement for a User

Create Entitlement. Grant Role to User.

Entitlements are used to grant System or Bank level roles to Users. (For Account level privileges, see Views)

For a System level Role (.e.g CanGetAnyUser), set bank_id to an empty string i.e. "bank_id":""

For a Bank level Role (e.g. CanCreateAccount), set bank_id to a valid value e.g. "bank_id":"my-bank-id"

Authentication is required and the user needs to be a Super Admin. Super Admins are listed in the Props file.

Authentication is Mandatory

URL Parameters:

USER_ID: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

JSON request body fields:

bank_id: gh.29.uk

role_name:

JSON response body fields:

bank_id: gh.29.uk

entitlement_id:

role_name:

Typical Successful Response: 

								
									
{
  "entitlement_id":"6fb17583-1e49-4435-bb74-a14fe0996723",
  "role_name":"CanQueryOtherUser",
  "bank_id":"gh.29.uk"
}
Required Roles:
  • CanCreateEntitlementAtOneBank - Please login to request this Role
  • CanCreateEntitlementAtAnyBank - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-20005: User not found. Please specify a valid value for USER_ID.
  • OBP-20050: Current User is not a Super Admin!
  • OBP-10001: Incorrect json format.
  • OBP-10007: Incorrect Role name:
  • OBP-30205: This entitlement is a Bank Role. Please set bank_id to a valid bank id.
  • OBP-30206: This entitlement is a System Role. Please set bank_id to empty string.
  • OBP-30216: Entitlement already exists for the user.
  • OBP-50000: Unknown Error.
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv2.0.0, function_name: by addEntitlement, operation_id: OBPv2.0.0-addEntitlement Tags: Role, Entitlement, User,

Add a Transaction Comment

Posts a comment about a transaction TRANSACTION_ID on a view VIEW_ID.

${authenticationRequiredMessage(false)}

Authentication is required since the comment is linked with the user.

Authentication is Mandatory

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

TRANSACTION_ID: 2fg8a7e4-6d02-40e3-a129-0b2bf89de8ub

VIEW_ID: owner

JSON request body fields:

value: 5987953

JSON response body fields:

date: 2020-01-27

display_name:

id: d8839721-ad8f-45dd-9f78-2080414b93f9

provider: ETHEREUM

user:

value: 5987953

Typical Successful Response: 

								
									
{
  "id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
  "value":"OBP",
  "date":"1100-01-01T00:00:00Z",
  "user":{
    "id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
    "provider":"http://127.0.0.1:8080",
    "display_name":"OBP"
  }
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-10001: Incorrect json format.
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-30022: The current view does not have the permission:
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv1.2.1, function_name: by addCommentForViewOnTransaction, operation_id: OBPv1.2.1-addCommentForViewOnTransaction Tags: Transaction-Metadata, Transaction,

Add a Transaction Tag

Posts a tag about a transaction TRANSACTION_ID on a view VIEW_ID.

Authentication is Mandatory

Authentication is required as the tag is linked with the user.

URL Parameters:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

TRANSACTION_ID: 2fg8a7e4-6d02-40e3-a129-0b2bf89de8ub

VIEW_ID: owner

JSON request body fields:

value: 5987953

JSON response body fields:

date: 2020-01-27

display_name:

id: d8839721-ad8f-45dd-9f78-2080414b93f9

provider: ETHEREUM

user:

value: 5987953

Typical Successful Response: 

								
									
{
  "id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
  "value":"OBP",
  "date":"1100-01-01T00:00:00Z",
  "user":{
    "id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
    "provider":"http://127.0.0.1:8080",
    "display_name":"OBP"
  }
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-10001: Incorrect json format.
  • OBP-30022: The current view does not have the permission:
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv1.2.1, function_name: by addTagForViewOnTransaction, operation_id: OBPv1.2.1-addTagForViewOnTransaction Tags: Transaction-Metadata, Transaction,

Create Transaction Request (ACCOUNT)

When using ACCOUNT, the payee is set in the request body.

Money goes into the BANK_ID and ACCOUNT_ID specified in the request body.

Initiate a Payment via creating a Transaction Request.

In OBP, a transaction request may or may not result in a transaction. However, a transaction only has one possible state: completed.

A Transaction Request can have one of several states: INITIATED, NEXT_CHALLENGE_PENDING etc.

Transactions are modeled on items in a bank statement that represent the movement of money.

Transaction Requests are requests to move money which may or may not succeed and thus result in a Transaction.

A Transaction Request might create a security challenge that needs to be answered before the Transaction Request proceeds.
In case 1 person needs to answer security challenge we have next flow of state of an transaction request:
INITIATED => COMPLETED
In case n persons needs to answer security challenge we have next flow of state of an transaction request:
INITIATED => NEXT_CHALLENGE_PENDING => ... => NEXT_CHALLENGE_PENDING => COMPLETED

The security challenge is bound to a user i.e. in case of right answer and the user is different than expected one the challenge will fail.

Rule for calculating number of security challenges:
If product Account attribute REQUIRED_CHALLENGE_ANSWERS=N then create N challenges
(one for every user that has a View where permission "can_add_transaction_request_to_any_account"=true)
In case REQUIRED_CHALLENGE_ANSWERS is not defined as an account attribute default value is 1.

Transaction Requests contain charge information giving the client the opportunity to proceed or not (as long as the challenge level is appropriate).

Transaction Requests can have one of several Transaction Request Types which expect different bodies. The escaped body is returned in the details key of the GET response.
This provides some commonality and one URL for many different payment or transfer types with enough flexibility to validate them differently.

The payer is set in the URL. Money comes out of the BANK_ID and ACCOUNT_ID specified in the URL.

In sandbox mode, TRANSACTION_REQUEST_TYPE is commonly set to ACCOUNT. See getTransactionRequestTypesSupportedByBank for all supported types.

In sandbox mode, if the amount is less than 1000 EUR (any currency, unless it is set differently on this server), the transaction request will create a transaction without a challenge, else the Transaction Request will be set to INITIALISED and a challenge will need to be answered.

If a challenge is created you must answer it using Answer Transaction Request Challenge before the Transaction is created.

You can transfer between different currency accounts. (new in 2.0.0). The currency in body must match the sending account.

The following static FX rates are available in sandbox mode:

https://obp-apiexplorer.joinfincubator.com/more?version=OBPv4.0.0&list-all-banks=false&core=&psd2=&obwg=#OBPv2_2_0-getCurrentFxRate

Transaction Requests satisfy PSD2 requirements thus:

1) A transaction can be initiated by a third party application.

2) The customer is informed of the charge that will incurred.

3) The call supports delegated authentication (OAuth)

See this python code for a complete example of this flow.

There is further documentation here

Authentication is Mandatory

URL Parameters:

ACCOUNT:

ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON request body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

amount: 10.12

bank_id: gh.29.uk

currency: EUR

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

to:

value: 5987953

JSON response body fields:

account:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

allowed_attempts: 5

amount: 10.12

bank_code: CGHZ

bank_id: gh.29.uk

branch_number:

challenge_type:

challenges: challenges

charge:

counterparty_id: 9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh

creditorAccount:

creditorName:

currency: EUR

date_of_birth: 2018-03-09

debtorAccount:

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

details:

end_date:

from:

future_date: 20200127

iban: DE91 1000 0000 0123 4567 89

id: d8839721-ad8f-45dd-9f78-2080414b93f9

instructedAmount: 100

kyc_document:

legal_name: Eveline Tripman

link:

message: 123456

mobile_phone_number: +49 30 901820

name: ACCOUNT_MANAGEMENT_FEE

nickname:

number:

otherAccountRoutingAddress: otherAccountRoutingAddress

otherAccountRoutingScheme: otherAccountRoutingScheme

otherAccountSecondaryRoutingAddress: otherAccountSecondaryRoutingAddress

otherAccountSecondaryRoutingScheme: otherAccountSecondaryRoutingScheme

otherBankRoutingAddress: otherBankRoutingAddress

otherBankRoutingScheme: otherBankRoutingScheme

otherBranchRoutingAddress: otherBranchRoutingAddress

otherBranchRoutingScheme: otherBranchRoutingScheme

start_date: 2020-01-27

status:

summary:

to:

transaction_ids:

transfer_type:

type:

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

value: 5987953

to_counterparty:

to_sandbox_tan:

to_sepa:

to_sepa_credit_transfers:

to_simple: to_simple

to_transfer_to_account:

to_transfer_to_atm:

to_transfer_to_phone:

Typical Successful Response: 

								
									
{
  "id":"4050046c-63b3-4868-8a22-14b4181d33a6",
  "type":"SANDBOX_TAN",
  "from":{
    "bank_id":"gh.29.uk",
    "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0"
  },
  "details":{
    "to_sandbox_tan":{
      "bank_id":"String",
      "account_id":"String"
    },
    "to_sepa":{
      "iban":"String"
    },
    "to_counterparty":{
      "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"
    },
    "to_simple":{
      "otherBankRoutingScheme":"BIC",
      "otherBankRoutingAddress":"GENODEM1GLS",
      "otherBranchRoutingScheme":"BRANCH-CODE",
      "otherBranchRoutingAddress":"DERBY6",
      "otherAccountRoutingScheme":"IBAN",
      "otherAccountRoutingAddress":"DE91 1000 0000 0123 4567 89",
      "otherAccountSecondaryRoutingScheme":"IBAN",
      "otherAccountSecondaryRoutingAddress":"DE91 1000 0000 0123 4567 89"
    },
    "to_transfer_to_phone":{
      "value":{
        "currency":"EUR",
        "amount":"0"
      },
      "description":"String",
      "message":"String",
      "from":{
        "mobile_phone_number":"+44 07972 444 876",
        "nickname":"String"
      },
      "to":{
        "mobile_phone_number":"+44 07972 444 876"
      }
    },
    "to_transfer_to_atm":{
      "value":{
        "currency":"EUR",
        "amount":"0"
      },
      "description":"String",
      "message":"String",
      "from":{
        "mobile_phone_number":"+44 07972 444 876",
        "nickname":"String"
      },
      "to":{
        "legal_name":"Eveline Tripman",
        "date_of_birth":"20181230",
        "mobile_phone_number":"+44 07972 444 876",
        "kyc_document":{
          "type":"String",
          "number":"String"
        }
      }
    },
    "to_transfer_to_account":{
      "value":{
        "currency":"EUR",
        "amount":"0"
      },
      "description":"String",
      "transfer_type":"String",
      "future_date":"20181230",
      "to":{
        "name":"String",
        "bank_code":"String",
        "branch_number":"String",
        "account":{
          "number":"String",
          "iban":"String"
        }
      }
    },
    "to_sepa_credit_transfers":{
      "debtorAccount":{
        "iban":"12345"
      },
      "instructedAmount":{
        "currency":"EUR",
        "amount":"0"
      },
      "creditorAccount":{
        "iban":"54321"
      },
      "creditorName":"John Miles"
    },
    "value":{
      "currency":"EUR",
      "amount":"100"
    },
    "description":"This an optional field. Maximum length is 2000. It can be any characters here."
  },
  "transaction_ids":["902ba3bb-dedd-45e7-9319-2fd3f2cd98a1"],
  "status":"COMPLETED",
  "start_date":"1100-01-01T00:00:00Z",
  "end_date":"1100-01-01T00:00:00Z",
  "challenges":[{
    "id":"2fg8a7e4-6d02-40e3-a129-0b2bf89de8ub",
    "user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
    "allowed_attempts":3,
    "challenge_type":"OBP_TRANSACTION_REQUEST_CHALLENGE",
    "link":"/obp/v4.0.0/banks/BANK_ID/accounts/ACCOUNT_ID/VIEW_ID/transaction-request-types/TRANSACTION_REQUEST_TYPE/transaction-requests/TRANSACTION_REQUEST_ID/challenge"
  }],
  "charge":{
    "summary":"Rent the flat",
    "value":{
      "currency":"EUR",
      "amount":"0"
    }
  }
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30111: Invalid Bank Id. The BANK_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-30110: Invalid Account Id. The ACCOUNT_ID should only contain 0-9/a-z/A-Z/'-'/'.'/'_', the length should be smaller than 255.
  • OBP-10001: Incorrect json format.
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-30003: Account not found. Please specify a valid value for ACCOUNT_ID.
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-40002: Insufficient authorisation to create TransactionRequest. The Transaction Request could not be created because the login user doesn't have access to the view of the from account or the consumer doesn't have the access to the view of the from account or the login user does not have the `CanCreateAnyTransactionRequest` role or the view does not have the permission can_add_transaction_request_to_any_account or the view does not have the permission can_add_transaction_request_to_beneficiary.
  • OBP-40001: Invalid value for TRANSACTION_REQUEST_TYPE
  • OBP-10001: Incorrect json format.
  • OBP-10002: Invalid Number. Could not convert value to a number.
  • OBP-40008: Can't send a payment with a value of 0 or less.
  • OBP-40003: Transaction Request Currency must be the same as From Account Currency.
  • OBP-00003: Transaction Requests is disabled in this API instance.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by createTransactionRequestAccount, operation_id: OBPv4.0.0-createTransactionRequestAccount Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Get User (Current)

Get the logged in user

Authentication is Mandatory

JSON response body fields:

account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

bank_id: gh.29.uk

email: felixsmith@example.com

entitlement_id:

entitlements:

list:

provider: ETHEREUM

provider_id:

role_name:

user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1

username: felixsmith

view_id: owner

views:

Typical Successful Response: 

								
									
{
  "user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
  "email":"felixsmith@example.com",
  "provider_id":"Chris",
  "provider":"http://127.0.0.1:8080",
  "username":"felixsmith",
  "entitlements":{
    "list":[{
      "entitlement_id":"6fb17583-1e49-4435-bb74-a14fe0996723",
      "role_name":"CanQueryOtherUser",
      "bank_id":"gh.29.uk"
    }]
  },
  "views":{
    "list":[{
      "bank_id":"gh.29.uk",
      "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
      "view_id":"owner"
    }]
  }
}
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.0.0, function_name: by getCurrentUser, operation_id: OBPv3.0.0-getCurrentUser Tags: User,

Create bank level Account Notification Webhook

Create a notification Webhook that will fire for all accounts on the specified Bank.

Webhooks are used to call external web services when certain events happen.

For instance, a webhook can be used to notify an external service if a transaction is created on an account.

When an account notification webhook fires it will POST to the URL you specify during the creation of the webhook.

Inside the payload you will find account_id and transaction_id and also user_ids and customer_ids of the Users / Customers linked to the Account.

The webhook will POST the following structure to your service:

{
"event_name": "OnCreateTransaction",
"event_id": "9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"bank_id": "gh.29.uk",
"account_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"transaction_id": "7ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"related_entities": [
{
"user_id": "8ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"customer_ids": ["3ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"]
}
]
}

Thus, your service should accept the above POST body structure.

In this way, your web service can be informed about an event on an account and act accordingly.

Further information about the account, transaction or related entities can then be retrieved using the standard REST APIs.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON request body fields:

http_method: GET

http_protocol:

url: http://www.example.com/id-docs/123/image.png

JSON response body fields:

bank_id: gh.29.uk

created_by_user_id:

http_method: GET

http_protocol:

trigger_name:

url: http://www.example.com/id-docs/123/image.png

webhook_id: webhook_id

Typical Successful Response: 

								
									
{
  "webhook_id":"fc23a7e2-7dd2-4bdf-a0b4-ae31232a4762",
  "bank_id":"gh.29.uk",
  "trigger_name":"OnCreateTransaction",
  "url":"https://localhost.openbankproject.com",
  "http_method":"POST",
  "http_protocol":"HTTP/1.1",
  "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"
}
Required Roles:
  • CanCreateAccountNotificationWebhookAtOneBank - Please login to request this Role
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-20001: User not logged in. Authentication is required!
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-50000: Unknown Error.
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by createBankAccountNotificationWebhook, operation_id: OBPv4.0.0-createBankAccountNotificationWebhook Tags: Webhook, Bank,