API Explorer

v5.1.0 filtered by tag: PSD2 (51 APIs)

Bank
Accounts
Views
Counterparties
Transactions

Get JSON Web Key (JWK)

Get the server's public JSON Web Key (JWK) set and certificate chain.
It is required by client applications to validate ID tokens, self-contained access tokens and other issued objects.

Authentication is Optional

JSON response body fields:

e:

kid:

kty:

n:

use:

Typical Successful Response:

								
									
{ "kty":"RSA", "e":"AQAB", "use":"sig", "kid":"fr6-BxXH5gikFeZ2O6rGk0LUmJpukeswASN_TMW8U_s", "n":"hrB0OWqg6AeNU3WCnhheG18R5EbQtdNYGOaSeylTjkj2lZr0_vkhNVYvase-CroxO4HOT06InxTYwLnmJiyv2cZxReuoVjTlk--olGu-9MZooiFiqWez0JzndyKxQ27OiAjFsMh0P04kaUXeHKhXRfiU7K2FqBshR1UlnWe7iHLkq2p9rrGjxQc7ff0w-Uc0f-8PWg36Y2Od7s65493iVQwnI13egqMaSvgB1s8_dgm08noEjhr8C5m1aKmr5oipWEPNi-SBV2VNuiCLR1IEPuXq0tOwwZfv31t34KPO-2H2bbaWmzGJy9mMOGqoNrbXyGiUZoyeHRELaNtm1GilyQ" }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by getServerJWK, operation_id: OBPv3.1.0-getServerJWK Tags: API, Account Information Service (AIS), PSD2,

Check Available Funds

Check Available Funds
Mandatory URL parameters:

  • amount=NUMBER
  • currency=STRING

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

answer:

available_funds_request_id:

date: 2020-01-27

Typical Successful Response:

								
									
{ "answer":"yes", "date":"2024-12-04T12:21:58Z", "available_funds_request_id":"c4ykz59svsr9b7fmdxk8ezs7" }
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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-20054: Invalid amount. Please specify a valid value for amount.
  • OBP-10003: Invalid Currency Value. It should be three letters ISO Currency Code.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by checkFundsAvailable, operation_id: OBPv3.1.0-checkFundsAvailable Tags: Account, Confirmation of Funds Service (PIIS), PSD2,

Get Account Balances

Get the Balances for one Account of the current User at one bank.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

JSON response body fields:

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

account_routings:

address:

amount: 10.12

balances: balances

bank_id: gh.29.uk

currency: EUR

label: My Account

scheme: OBP

type:

Typical Successful Response:

								
									
{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_routings":[{ "scheme":"accountNumber", "address":"123456" }], "label":"My Account", "balances":[{ "type":"", "currency":"EUR", "amount":"10" }] }
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-30065: Cannot find account access.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getBankAccountBalancesForCurrentUser, operation_id: OBPv4.0.0-getBankAccountBalancesForCurrentUser Tags: Account, Account Information Service (AIS), PSD2,

Get Account Balances by BANK_ID

Get the Balances for the Account specified by BANK_ID.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

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

account_routings:

accounts:

address:

amount: 10.12

balances: balances

bank_id: gh.29.uk

currency: EUR

label: My Account

scheme: OBP

type:

Typical Successful Response:

								
									
{ "accounts":[{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_routings":[{ "scheme":"accountNumber", "address":"123456" }], "label":"My Account", "balances":[{ "type":"", "currency":"EUR", "amount":"10" }] }] }
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.
Connector Methods:
Version: OBPv5.1.0, function_name: by getBankAccountsBalancesThroughView, operation_id: OBPv5.1.0-getBankAccountsBalancesThroughView Tags: Account, Account Information Service (AIS), PSD2,

Get Account Balances by BANK_ID

Get the Balances for the Account specified by BANK_ID.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

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

account_routings:

accounts:

address:

amount: 10.12

balances: balances

bank_id: gh.29.uk

currency: EUR

label: My Account

scheme: OBP

type:

Typical Successful Response:

								
									
{ "accounts":[{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_routings":[{ "scheme":"accountNumber", "address":"123456" }], "label":"My Account", "balances":[{ "type":"", "currency":"EUR", "amount":"10" }] }] }
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.
Connector Methods:
Version: OBPv5.1.0, function_name: by getBankAccountsBalances, operation_id: OBPv5.1.0-getBankAccountsBalances Tags: Account, Account Information Service (AIS), PSD2,

Get Account Balances by BANK_ID and ACCOUNT_ID through the VIEW_ID

Get the Balances for the Account specified by BANK_ID and ACCOUNT_ID through the VIEW_ID.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

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

account_routings:

address:

amount: 10.12

balances: balances

bank_id: gh.29.uk

currency: EUR

label: My Account

scheme: OBP

type:

Typical Successful Response:

								
									
{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_routings":[{ "scheme":"accountNumber", "address":"123456" }], "label":"My Account", "balances":[{ "type":"", "currency":"EUR", "amount":"10" }] }
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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.1.0, function_name: by getBankAccountBalances, operation_id: OBPv5.1.0-getBankAccountBalances Tags: Account, Account Information Service (AIS), PSD2,

Get Account by Id (Core)

Information returned about the account specified by ACCOUNT_ID:

  • Number - The human readable account number given by the bank that identifies the account.
  • Label - A label given by the owner of the account
  • Owners - Users that own this account
  • Type - The type of account
  • Balance - Currency and Value
  • Account Routings - A list that might include IBAN or national account identifiers
  • Account Rules - A list that might include Overdraft and other bank specific rules
  • Tags - A list of Tags assigned to this account

This call returns the owner view and requires access to that view.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

JSON response body fields:

account_routings:

address:

amount: 10.12

balance: 10

bank_id: gh.29.uk

currency: EUR

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

label: My Account

number:

product_code: 1234BW

scheme: OBP

views_basic:

Typical Successful Response:

								
									
{ "id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "bank_id":"gh.29.uk", "label":"My Account", "number":"546387432", "product_code":"AC", "balance":{ "currency":"EUR", "amount":"0" }, "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "views_basic":["owner"] }
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-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getCoreAccountById, operation_id: OBPv4.0.0-getCoreAccountById Tags: Account, Account Information Service (AIS), PSD2,

Get Account by Id (Core) through the VIEW_ID

Information returned about the account through VIEW_ID :

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

account_routings:

address:

amount: 10.12

balance: 10

bank_id: gh.29.uk

currency: EUR

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

label: My Account

number:

product_code: 1234BW

scheme: OBP

views_basic:

Typical Successful Response:

								
									
{ "id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "bank_id":"gh.29.uk", "label":"My Account", "number":"546387432", "product_code":"AC", "balance":{ "currency":"EUR", "amount":"0" }, "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "views_basic":["owner"] }
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-50000: Unknown Error.
Connector Methods:
Version: OBPv5.1.0, function_name: by getCoreAccountByIdThroughView, operation_id: OBPv5.1.0-getCoreAccountByIdThroughView Tags: Account, Account Information Service (AIS), PSD2,

Get Accounts Held

Get Accounts held by the current User if even the User has not been assigned the owner View yet.

Can be used to onboard the account to the API - since all other account and transaction endpoints require views to be assigned.

optional request parameters:

  • account_type_filter: one or many accountType value, split by comma
  • account_type_filter_operation: the filter type of account_type_filter, value must be INCLUDE or EXCLUDE

whole url example:
/banks/BANK_ID/accounts-held?account_type_filter=330,CURRENT+PLUS&account_type_filter_operation=INCLUDE

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

account_routings:

accounts:

address:

bank_id: gh.29.uk

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

label: My Account

number:

scheme: OBP

Typical Successful Response:

								
									
{ "accounts":[{ "id":"12314", "label":"My Account", "bank_id":"123", "number":"123", "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }] }] }
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 getAccountsHeld, operation_id: OBPv3.0.0-getAccountsHeld Tags: Account, Account Information Service (AIS), View-Custom, PSD2,

Get Accounts at Bank (IDs only)

Returns only the list of accounts ids at BANK_ID that the user has access to.

Each account must have at least one private View.

For each account the API returns its account ID.

If you want to see more information on the Views, use the Account Detail call.

optional request parameters:

  • account_type_filter: one or many accountType value, split by comma
  • account_type_filter_operation: the filter type of account_type_filter, value must be INCLUDE or EXCLUDE

whole url example:
/banks/BANK_ID/accounts/account_ids/private?account_type_filter=330,CURRENT+PLUS&account_type_filter_operation=INCLUDE

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

accounts:

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

Typical Successful Response:

								
									
{ "accounts":[{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf" }] }
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.
Connector Methods:
Version: OBPv3.0.0, function_name: by getPrivateAccountIdsbyBankId, operation_id: OBPv3.0.0-getPrivateAccountIdsbyBankId Tags: Account, Account Information Service (AIS), PSD2,

Get Accounts at Bank (Minimal)

Returns the minimal list of private accounts at BANK_ID that the user has access to.
For each account, the API returns the ID, routing addresses and the views available to the current user.

If you want to see more information on the Views, use the Account Detail call.

optional request parameters:

  • account_type_filter: one or many accountType value, split by comma
  • account_type_filter_operation: the filter type of account_type_filter, value must be INCLUDE or EXCLUDE

whole url example:
/banks/BANK_ID/accounts/private?account_type_filter=330,CURRENT+PLUS&account_type_filter_operation=INCLUDE

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

account_routings:

account_type: AC

accounts:

address:

bank_id: gh.29.uk

description: Description of the object. Maximum length is 2000. It can be any characters here.

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

is_public: false

label: My Account

scheme: OBP

short_name:

views:

Typical Successful Response:

								
									
{ "accounts":[{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "label":"String", "bank_id":"gh.29.uk", "account_type":"330", "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "views":[{ "id":"owner", "short_name":"owner", "description":"This view is for the owner for the account.", "is_public":false }] }] }
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.
Connector Methods:
Version: OBPv3.0.0, function_name: by privateAccountsAtOneBank, operation_id: OBPv3.0.0-privateAccountsAtOneBank Tags: Account, Account Information Service (AIS), PSD2,

Get Accounts at all Banks (private)

Returns the list of accounts containing private views for the user.
Each account lists the views available to the user.

optional request parameters:

  • account_type_filter: one or many accountType value, split by comma
  • account_type_filter_operation: the filter type of account_type_filter, value must be INCLUDE or EXCLUDE

whole url example:
/my/accounts?account_type_filter=330,CURRENT+PLUS&account_type_filter_operation=INCLUDE

Authentication is Mandatory

JSON response body fields:

account_routings:

account_type: AC

accounts:

address:

bank_id: gh.29.uk

description: Description of the object. Maximum length is 2000. It can be any characters here.

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

is_public: false

label: My Account

scheme: OBP

short_name:

views:

Typical Successful Response:

								
									
{ "accounts":[{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "label":"String", "bank_id":"gh.29.uk", "account_type":"330", "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "views":[{ "id":"owner", "short_name":"owner", "description":"This view is for the owner for the account.", "is_public":false }] }] }
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 corePrivateAccountsAllBanks, operation_id: OBPv3.0.0-corePrivateAccountsAllBanks Tags: Account, Account Information Service (AIS), PrivateData, PSD2,

Get Bank

Get the bank specified by BANK_ID
Returns information about a single bank specified by BANK_ID including:

  • Bank code and full name of bank
  • Logo URL
  • Website

Authentication is Optional

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

address:

bank_code: CGHZ

bank_routings: bank routing in form of (scheme, address)

full_name: full name string

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

logo: logo url

name: ACCOUNT_MANAGEMENT_FEE

scheme: OBP

value: 5987953

website: www.openbankproject.com

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

Typical Successful Response:

								
									
{ "id":"gh.29.uk", "bank_code":"CGHZ", "full_name":"bank fullName string", "logo":"bank logoUrl string", "website":"bank logoUrl string", "bank_routings":[{ "scheme":"OBP", "address":"gh.29.uk" }], "attributes":[{ "name":"ACCOUNT_MANAGEMENT_FEE", "value":"5987953" }] }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
Connector Methods:
Version: OBPv5.0.0, function_name: by getBank, operation_id: OBPv5.0.0-getBank Tags: Bank, Account Information Service (AIS), PSD2,

Get Settlement accounts at Bank

Get settlement accounts on this API instance
Returns a list of settlement accounts at this Bank

Note: a settlement account is considered as a bank account.
So you can update it and add account attributes to it using the regular account endpoints

Authentication is Mandatory

URL Parameters:

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

payment_system: SEPA

product_code: 1234BW

scheme: OBP

settlement_accounts:

type:

value: 5987953

product_instance_code: product_instance_code

Typical Successful Response:

								
									
{ "settlement_accounts":[{ "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "payment_system":"SEPA", "balance":{ "currency":"EUR", "amount":"0" }, "label":"My Account", "branch_id":"DERBY6", "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "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:
  • CanGetSettlementAccountAtOneBank - 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-20006: User is missing one or more roles:
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getSettlementAccounts, operation_id: OBPv4.0.0-getSettlementAccounts Tags: Bank, PSD2,

Get Transaction Types at Bank

Get Transaction Types for the bank specified by BANK_ID:

Lists the possible Transaction Types available at the bank (as opposed to Transaction Request Types which are the possible ways Transactions can be created by this API Server).

  • id : Unique transaction type id across the API instance. SHOULD be a UUID. MUST be unique.
  • bank_id : The bank that supports this TransactionType
  • short_code : A short code (SHOULD have no-spaces) which MUST be unique across the bank. May be stored with Transactions to link here
  • summary : A succinct summary
  • description : A longer description
  • charge : The charge to the customer for each one of these

Authentication is Optional

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

amount: 10.12

bank_id: gh.29.uk

charge:

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

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

short_code:

summary:

transaction_types:

value: 5987953

Typical Successful Response:

								
									
{ "transaction_types":[{ "id":{ "value":"123" }, "bank_id":"gh.29.uk", "short_code":"PlaceholderString", "summary":"PlaceholderString", "description":"PlaceholderString", "charge":{ "currency":"EUR", "amount":"0" } }] }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv2.0.0, function_name: by getTransactionTypes, operation_id: OBPv2.0.0-getTransactionTypes Tags: Bank, Account Information Service (AIS), PSD2,

Get Banks

Get banks on this API instance
Returns a list of banks supported on this server:

  • ID used as parameter in URLs
  • Short and full name of bank
  • Logo URL
  • Website

Authentication is Optional

JSON response body fields:

address:

bank_routings: bank routing in form of (scheme, address)

banks:

full_name: full name string

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

logo: logo url

name: ACCOUNT_MANAGEMENT_FEE

scheme: OBP

short_name:

value: 5987953

website: www.openbankproject.com

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

Typical Successful Response:

								
									
{ "banks":[{ "id":"gh.29.uk", "short_name":"short_name ", "full_name":"full_name", "logo":"logo", "website":"www.openbankproject.com", "bank_routings":[{ "scheme":"OBP", "address":"gh.29.uk" }], "attributes":[{ "name":"ACCOUNT_MANAGEMENT_FEE", "value":"5987953" }] }] }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getBanks, operation_id: OBPv4.0.0-getBanks Tags: BankAccountTag1, BankAccountTag1, BankAccountTag1, Bank, Account Information Service (AIS), PSD2,

Answer Consent Challenge

An OBP Consent allows the holder of the Consent to call one or more endpoints.

Consents must be created and authorisied using SCA (Strong Customer Authentication).

That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.

Each Consent has one of the following states: INITIATED, ACCEPTED, REJECTED, REVOKED, RECEIVED, VALID, REVOKEDBYPSU, EXPIRED, TERMINATEDBYTPP, AUTHORISED, AWAITINGAUTHORISATION.

Each Consent is bound to a consumer i.e. you need to identify yourself over request header value Consumer-Key.
For example:
GET /obp/v4.0.0/users/current HTTP/1.1
Host: 127.0.0.1:8080
Consent-JWT: eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEFueVVzZXIiLCJiYW5rX2lkIjoiIn
1dLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIzNDc1MDEzZi03YmY5LTQyNj
EtOWUxYy0xZTdlNWZjZTJlN2UiLCJhdWQiOiI4MTVhMGVmMS00YjZhLTQyMDUtYjExMi1lNDVmZDZmNGQzYWQiLCJuYmYiOjE1ODA3NDE2NjcsIml
zcyI6Imh0dHA6XC9cLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNTgwNzQ1MjY3LCJpYXQiOjE1ODA3NDE2NjcsImp0aSI6ImJkYzVjZTk5LTE2ZTY
tNDM4Yi1hNjllLTU3MTAzN2RhMTg3OCIsInZpZXdzIjpbXX0.L3fEEEhdCVr3qnmyRKBBUaIQ7dk1VjiFaEBW8hUNjfg

Consumer-Key: ejznk505d132ryomnhbx1qmtohurbsbb0kijajsk
cache-control: no-cache

Maximum time to live of the token is specified over props value consents.max_time_to_live. In case isn't defined default value is 3600 seconds.

Example of POST JSON:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com",
"valid_from": "2020-02-07T08:43:34Z",
"time_to_live": 3600
}
Please note that only optional fields are: consumer_id, valid_from and time_to_live.
In case you omit they the default values are used:
consumer_id = consumer of current user
valid_from = current time
time_to_live = consents.max_time_to_live

This endpoint is used to confirm a Consent previously created.

The User must supply a code that was sent out of band (OOB) for example via an SMS.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

CONSENT_ID:

JSON request body fields:

answer:

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED" }
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-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by answerConsentChallenge, operation_id: OBPv3.1.0-answerConsentChallenge Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent (EMAIL)

This endpoint starts the process of creating a Consent.

The Consent is created in an INITIATED state.

A One Time Password (OTP) (AKA security challenge) is sent Out of Band (OOB) to the User via the transport defined in SCA_METHOD
SCA_METHOD is typically "SMS","EMAIL" or "IMPLICIT". "EMAIL" is used for testing purposes. OBP mapped mode "IMPLICIT" is "EMAIL".
Other mode, bank can decide it in the connector method 'getConsentImplicitSCA'.

When the Consent is created, OBP (or a backend system) stores the challenge so it can be checked later against the value supplied by the User with the Answer Consent Challenge endpoint.

An OBP Consent allows the holder of the Consent to call one or more endpoints.

Consents must be created and authorisied using SCA (Strong Customer Authentication).

That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.

Each Consent has one of the following states: INITIATED, ACCEPTED, REJECTED, REVOKED, RECEIVED, VALID, REVOKEDBYPSU, EXPIRED, TERMINATEDBYTPP, AUTHORISED, AWAITINGAUTHORISATION.

Each Consent is bound to a consumer i.e. you need to identify yourself over request header value Consumer-Key.
For example:
GET /obp/v4.0.0/users/current HTTP/1.1
Host: 127.0.0.1:8080
Consent-JWT: eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEFueVVzZXIiLCJiYW5rX2lkIjoiIn
1dLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIzNDc1MDEzZi03YmY5LTQyNj
EtOWUxYy0xZTdlNWZjZTJlN2UiLCJhdWQiOiI4MTVhMGVmMS00YjZhLTQyMDUtYjExMi1lNDVmZDZmNGQzYWQiLCJuYmYiOjE1ODA3NDE2NjcsIml
zcyI6Imh0dHA6XC9cLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNTgwNzQ1MjY3LCJpYXQiOjE1ODA3NDE2NjcsImp0aSI6ImJkYzVjZTk5LTE2ZTY
tNDM4Yi1hNjllLTU3MTAzN2RhMTg3OCIsInZpZXdzIjpbXX0.L3fEEEhdCVr3qnmyRKBBUaIQ7dk1VjiFaEBW8hUNjfg

Consumer-Key: ejznk505d132ryomnhbx1qmtohurbsbb0kijajsk
cache-control: no-cache

Maximum time to live of the token is specified over props value consents.max_time_to_live. In case isn't defined default value is 3600 seconds.

Example of POST JSON:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com",
"valid_from": "2020-02-07T08:43:34Z",
"time_to_live": 3600
}
Please note that only optional fields are: consumer_id, valid_from and time_to_live.
In case you omit they the default values are used:
consumer_id = consumer of current user
valid_from = current time
time_to_live = consents.max_time_to_live

Authentication is Mandatory

Example 1:
{
"everything": true,
"views": [],
"entitlements": [],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"phone_number": "+49 170 1234567"
}

Please note that consumer_id is optional field
Example 2:
{
"everything": true,
"views": [],
"entitlements": [],
"phone_number": "+49 170 1234567"
}

Please note if everything=false you need to explicitly specify views and entitlements
Example 3:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"phone_number": "+49 170 1234567"
}

URL Parameters:

BANK_ID: gh.29.uk

EMAIL: felixsmith@example.com

JSON request body fields:

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

bank_id: gh.29.uk

email: felixsmith@example.com

entitlements:

everything:

role_name:

view_id: owner

views:

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

time_to_live:

valid_from: 2020-01-27

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED" }
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-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by createConsentEmail, operation_id: OBPv3.1.0-createConsentEmail Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent (IMPLICIT)

This endpoint starts the process of creating a Consent.

The Consent is created in an INITIATED state.

A One Time Password (OTP) (AKA security challenge) is sent Out of Band (OOB) to the User via the transport defined in SCA_METHOD
SCA_METHOD is typically "SMS","EMAIL" or "IMPLICIT". "EMAIL" is used for testing purposes. OBP mapped mode "IMPLICIT" is "EMAIL".
Other mode, bank can decide it in the connector method 'getConsentImplicitSCA'.

When the Consent is created, OBP (or a backend system) stores the challenge so it can be checked later against the value supplied by the User with the Answer Consent Challenge endpoint.

An OBP Consent allows the holder of the Consent to call one or more endpoints.

Consents must be created and authorisied using SCA (Strong Customer Authentication).

That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.

Each Consent has one of the following states: INITIATED, ACCEPTED, REJECTED, REVOKED, RECEIVED, VALID, REVOKEDBYPSU, EXPIRED, TERMINATEDBYTPP, AUTHORISED, AWAITINGAUTHORISATION.

Each Consent is bound to a consumer i.e. you need to identify yourself over request header value Consumer-Key.
For example:
GET /obp/v4.0.0/users/current HTTP/1.1
Host: 127.0.0.1:8080
Consent-JWT: eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEFueVVzZXIiLCJiYW5rX2lkIjoiIn
1dLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIzNDc1MDEzZi03YmY5LTQyNj
EtOWUxYy0xZTdlNWZjZTJlN2UiLCJhdWQiOiI4MTVhMGVmMS00YjZhLTQyMDUtYjExMi1lNDVmZDZmNGQzYWQiLCJuYmYiOjE1ODA3NDE2NjcsIml
zcyI6Imh0dHA6XC9cLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNTgwNzQ1MjY3LCJpYXQiOjE1ODA3NDE2NjcsImp0aSI6ImJkYzVjZTk5LTE2ZTY
tNDM4Yi1hNjllLTU3MTAzN2RhMTg3OCIsInZpZXdzIjpbXX0.L3fEEEhdCVr3qnmyRKBBUaIQ7dk1VjiFaEBW8hUNjfg

Consumer-Key: ejznk505d132ryomnhbx1qmtohurbsbb0kijajsk
cache-control: no-cache

Maximum time to live of the token is specified over props value consents.max_time_to_live. In case isn't defined default value is 3600 seconds.

Example of POST JSON:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com",
"valid_from": "2020-02-07T08:43:34Z",
"time_to_live": 3600
}
Please note that only optional fields are: consumer_id, valid_from and time_to_live.
In case you omit they the default values are used:
consumer_id = consumer of current user
valid_from = current time
time_to_live = consents.max_time_to_live

Authentication is Mandatory

Example 1:
{
"everything": true,
"views": [],
"entitlements": [],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
}

Please note that consumer_id is optional field
Example 2:
{
"everything": true,
"views": [],
"entitlements": [],
}

Please note if everything=false you need to explicitly specify views and entitlements
Example 3:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
}

URL Parameters:

BANK_ID: gh.29.uk

IMPLICIT: IMPLICIT

JSON request body fields:

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

bank_id: gh.29.uk

entitlements:

everything:

role_name:

view_id: owner

views:

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

time_to_live:

valid_from: 2020-01-27

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED" }
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-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-00010: Missing props value at this API instance -
  • OBP-35010: SMS server is not working or SMS server can not send the message to the phone number:
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by createConsentImplicit, operation_id: OBPv3.1.0-createConsentImplicit Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent (SMS)

This endpoint starts the process of creating a Consent.

The Consent is created in an INITIATED state.

A One Time Password (OTP) (AKA security challenge) is sent Out of Band (OOB) to the User via the transport defined in SCA_METHOD
SCA_METHOD is typically "SMS","EMAIL" or "IMPLICIT". "EMAIL" is used for testing purposes. OBP mapped mode "IMPLICIT" is "EMAIL".
Other mode, bank can decide it in the connector method 'getConsentImplicitSCA'.

When the Consent is created, OBP (or a backend system) stores the challenge so it can be checked later against the value supplied by the User with the Answer Consent Challenge endpoint.

An OBP Consent allows the holder of the Consent to call one or more endpoints.

Consents must be created and authorisied using SCA (Strong Customer Authentication).

That is, Consents can be created by an authorised User via the OBP REST API but they must be confirmed via an out of band (OOB) mechanism such as a code sent to a mobile phone.

Each Consent has one of the following states: INITIATED, ACCEPTED, REJECTED, REVOKED, RECEIVED, VALID, REVOKEDBYPSU, EXPIRED, TERMINATEDBYTPP, AUTHORISED, AWAITINGAUTHORISATION.

Each Consent is bound to a consumer i.e. you need to identify yourself over request header value Consumer-Key.
For example:
GET /obp/v4.0.0/users/current HTTP/1.1
Host: 127.0.0.1:8080
Consent-JWT: eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOlt7InJvbGVfbmFtZSI6IkNhbkdldEFueVVzZXIiLCJiYW5rX2lkIjoiIn
1dLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIzNDc1MDEzZi03YmY5LTQyNj
EtOWUxYy0xZTdlNWZjZTJlN2UiLCJhdWQiOiI4MTVhMGVmMS00YjZhLTQyMDUtYjExMi1lNDVmZDZmNGQzYWQiLCJuYmYiOjE1ODA3NDE2NjcsIml
zcyI6Imh0dHA6XC9cLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNTgwNzQ1MjY3LCJpYXQiOjE1ODA3NDE2NjcsImp0aSI6ImJkYzVjZTk5LTE2ZTY
tNDM4Yi1hNjllLTU3MTAzN2RhMTg3OCIsInZpZXdzIjpbXX0.L3fEEEhdCVr3qnmyRKBBUaIQ7dk1VjiFaEBW8hUNjfg

Consumer-Key: ejznk505d132ryomnhbx1qmtohurbsbb0kijajsk
cache-control: no-cache

Maximum time to live of the token is specified over props value consents.max_time_to_live. In case isn't defined default value is 3600 seconds.

Example of POST JSON:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com",
"valid_from": "2020-02-07T08:43:34Z",
"time_to_live": 3600
}
Please note that only optional fields are: consumer_id, valid_from and time_to_live.
In case you omit they the default values are used:
consumer_id = consumer of current user
valid_from = current time
time_to_live = consents.max_time_to_live

Authentication is Mandatory

Example 1:
{
"everything": true,
"views": [],
"entitlements": [],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com"
}

Please note that consumer_id is optional field
Example 2:
{
"everything": true,
"views": [],
"entitlements": [],
"email": "eveline@example.com"
}

Please note if everything=false you need to explicitly specify views and entitlements
Example 3:
{
"everything": false,
"views": [
{
"bank_id": "GENODEM1GLS",
"account_id": "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"view_id": "owner"
}
],
"entitlements": [
{
"bank_id": "GENODEM1GLS",
"role_name": "CanGetCustomer"
}
],
"consumer_id": "7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh",
"email": "eveline@example.com"
}

URL Parameters:

BANK_ID: gh.29.uk

SMS:

JSON request body fields:

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

bank_id: gh.29.uk

entitlements:

everything:

phone_number:

role_name:

view_id: owner

views:

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

time_to_live:

valid_from: 2020-01-27

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED" }
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-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-00010: Missing props value at this API instance -
  • OBP-35010: SMS server is not working or SMS server can not send the message to the phone number:
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.1.0, function_name: by createConsentSms, operation_id: OBPv3.1.0-createConsentSms Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent By CONSENT_REQUEST_ID (EMAIL)

This endpoint continues the process of creating a Consent.

It starts the SCA flow which changes the status of the consent from INITIATED to ACCEPTED or REJECTED.

Please note that the Consent cannot elevate the privileges of the logged in user.

Authentication is Mandatory

URL Parameters:

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

EMAIL: felixsmith@example.com

JSON request body fields:

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createConsentByConsentRequestIdEmail, operation_id: OBPv5.0.0-createConsentByConsentRequestIdEmail Tags: Consent, Account Information Service (AIS), PSD2, VRP,

Create Consent By CONSENT_REQUEST_ID (IMPLICIT)

This endpoint continues the process of creating a Consent. It starts the SCA flow which changes the status of the consent from INITIATED to ACCEPTED or REJECTED.
Please note that the Consent cannot elevate the privileges logged in user already have.

Authentication is Mandatory

URL Parameters:

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

IMPLICIT: IMPLICIT

JSON request body fields:

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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-35029: The CONSENT_REQUEST_ID is invalid.
  • OBP-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-00010: Missing props value at this API instance -
  • OBP-35010: SMS server is not working or SMS server can not send the message to the phone number:
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createConsentByConsentRequestIdImplicit, operation_id: OBPv5.0.0-createConsentByConsentRequestIdImplicit Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent By CONSENT_REQUEST_ID (SMS)

This endpoint continues the process of creating a Consent. It starts the SCA flow which changes the status of the consent from INITIATED to ACCEPTED or REJECTED.

Please note that the Consent you are creating cannot exceed the entitlements that the User creating this consents already has.

Authentication is Mandatory

URL Parameters:

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

SMS:

JSON request body fields:

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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-35029: The CONSENT_REQUEST_ID is invalid.
  • OBP-35009: Only SMS, EMAIL and IMPLICIT are supported as SCA methods.
  • OBP-35013: Consents can only contain Roles that you already have access to.
  • OBP-35014: Consents can only contain Views that you already have access to.
  • OBP-30019: Consumer not found. Please specify a valid value for CONSUMER_ID.
  • OBP-20058: Consumer is disabled.
  • OBP-00010: Missing props value at this API instance -
  • OBP-35010: SMS server is not working or SMS server can not send the message to the phone number:
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createConsentByConsentRequestIdSms, operation_id: OBPv5.0.0-createConsentByConsentRequestIdSms Tags: Consent, Account Information Service (AIS), PSD2,

Create Consent Request

Client Authentication (mandatory)

It is used when applications request an access token to access their own resources, not on behalf of a user.

The client needs to authenticate themselves for this request.
In case of public client we use client_id and private key to obtain access token, otherwise we use client_id and client_secret.
The obtained access token is used in the HTTP Bearer auth header of our request.

Example:
Authorization: Bearer eXtneO-THbQtn3zvK_kQtXXfvOZyZFdBCItlPDbR2Bk.dOWqtXCtFX-tqGTVR0YrIjvAolPIVg7GZ-jz83y6nA0

After successfully creating the VRP consent request, you need to call the Create Consent By CONSENT_REQUEST_ID endpoint to finalize the consent.

Authentication is Optional

JSON request body fields:

account_access: account_access

account_routing:

address:

bank_id: gh.29.uk

everything:

role_name:

scheme: OBP

view_id: owner

bank_id: gh.29.uk

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

email: felixsmith@example.com

entitlements:

phone_number:

time_to_live:

valid_from: 2020-01-27

JSON response body fields:

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

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

payload: payload

Typical Successful Response:

								
									
{ "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "payload":{ "everything":false, "account_access":[{ "account_routing":{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }, "view_id":"owner" }], "phone_number":"+44 07972 444 876", "valid_from":"2022-06-14T12:42:00Z", "time_to_live":3600 }, "consumer_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh" }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-10001: Incorrect json format.
  • OBP-35020: You exceeded max value of time to live of consents.
  • OBP-20306: PEM Encoded Certificate cannot be found at request header.
  • OBP-20300: PEM Encoded Certificate issue.
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by createConsentRequest, operation_id: OBPv5.0.0-createConsentRequest Tags: Consent, Account Information Service (AIS), PSD2,

Get Consent By Consent Id

This endpoint gets the Consent By consent id.

Authentication is Mandatory

URL Parameters:

CONSENT_ID:

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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: OBPv5.1.0, function_name: by getConsentByConsentIdViaConsumer, operation_id: OBPv5.1.0-getConsentByConsentIdViaConsumer Tags: Consent, Account Information Service (AIS), PSD2,

Get Consent By Consent Id

This endpoint gets the Consent By consent id.

Authentication is Mandatory

URL Parameters:

CONSENT_ID:

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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: OBPv5.1.0, function_name: by getConsentByConsentId, operation_id: OBPv5.1.0-getConsentByConsentId Tags: Consent, Account Information Service (AIS), PSD2,

Get Consent By Consent Request Id

This endpoint gets the Consent By consent request id.

Authentication is Mandatory

URL Parameters:

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

JSON response body fields:

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

bank_id: gh.29.uk

consent_id:

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

helper_info: helper_info

jwt:

status:

view_id: owner

account_access: account_access

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

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "account_access":{ "bank_id":"gh.29.uk", "account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "view_id":"owner", "helper_info":{ "counterparty_id":["9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh"] } } }
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: OBPv5.0.0, function_name: by getConsentByConsentRequestId, operation_id: OBPv5.0.0-getConsentByConsentRequestId Tags: Consent, Account Information Service (AIS), PSD2,

Get Consent Request

Authentication is Optional

URL Parameters:

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

JSON response body fields:

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

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

payload: payload

Typical Successful Response:

								
									
{ "consent_request_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "payload":{ "everything":false, "account_access":[{ "account_routing":{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }, "view_id":"owner" }], "phone_number":"+44 07972 444 876", "valid_from":"2022-06-14T12:42:00Z", "time_to_live":3600 }, "consumer_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh" }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-10001: Incorrect json format.
  • OBP-35020: You exceeded max value of time to live of consents.
  • OBP-20306: PEM Encoded Certificate cannot be found at request header.
  • OBP-20300: PEM Encoded Certificate issue.
  • OBP-50200: Connector cannot return the data we requested.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv5.0.0, function_name: by getConsentRequest, operation_id: OBPv5.0.0-getConsentRequest Tags: Consent, Account Information Service (AIS), PSD2,

Get Consents at Bank

This endpoint gets the Consents at Bank by BANK_ID.

Authentication is Mandatory

1 limit (for pagination: defaults to 50) eg:limit=200

2 offset (for pagination: zero index, defaults to 0) eg: offset=10

3 consumer_id (ignore if omitted)

4 user_id (ignore if omitted)

5 status (ignore if omitted)

eg: /management/consents/banks/BANK_ID?&consumer_id=78&limit=10&offset=10

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

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

api_standard: api_standard

api_version:

aud: String

bank_id: gh.29.uk

consent_reference_id: consent_reference_id

consents:

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

createdByUserId: createdByUserId

created_by_user_id:

entitlements:

exp: String

iat: String

iss: String

jti: String

jwt:

jwt_payload: jwt_payload

last_action_date: last_action_date

last_usage_date: last_usage_date

nbf: String

status:

sub: felixsmith

view_id: owner

views:

access: access

accounts:

allPsd2: allPsd2

availableAccounts: availableAccounts

balances: balances

bban: bban

currency: EUR

email: felixsmith@example.com

iban: DE91 1000 0000 0123 4567 89

maskedPan: maskedPan

msisdn: msisdn

name: ACCOUNT_MANAGEMENT_FEE

pan: pan

transactions:

Typical Successful Response:

								
									
{ "consents":[{ "consent_reference_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "consumer_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "status":"INITIATED", "last_action_date":"2020-01-27", "last_usage_date":"2021-04-08T09:12:27Z", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiIiLCJzdWIiOiJmY2YzNDZkMi0xNTNiLTQ0MzAtOWE4Zi1mMzU3Njg1MzM5ODciLCJhdWQiOiIyNjY0NjUwYy04MDkwLTQ4MWUtOGJkOC0wM2E5MmY5Yzg3ZWEiLCJuYmYiOjE3MzAzNzMyNzEsImFjY2VzcyI6eyJhY2NvdW50cyI6W3siaWJhbiI6IlJTMzUyNjAwMDU2MDEwMDE2MTEzNzkifV19LCJpc3MiOiJodHRwczovLzEyNy4wLjAuMTo4MDgwIiwiZXhwIjoxNzMwOTM3NjAwLCJpYXQiOjE3MzAzNzMyNzEsImp0aSI6ImQzM2Y3NDYzLWVlNDktNGU4YS04YTkyLTYxMzhkYzE4M2QxNiIsInZpZXdzIjpbeyJiYW5rX2lkIjoibmxia2IiLCJhY2NvdW50X2lkIjoiOTUzODkyOTctNDVjNC00MGViLTllZmQtMzMxYmExOTQzZGE0Iiwidmlld19pZCI6IlJlYWRBY2NvdW50c0Jlcmxpbkdyb3VwIn1dfQ.SXE4W34596lrSXqZrA8cvQs_fvhjWYilU8VDpXZ3C3Y", "jwt_payload":{ "createdByUserId":"", "sub":"fcf346d2-153b-4430-9a8f-f35768533987", "iss":"https://127.0.0.1:8080", "aud":"2664650c-8090-481e-8bd8-03a92f9c87ea", "jti":"d33f7463-ee49-4e8a-8a92-6138dc183d16", "iat":1730373271, "nbf":1730373271, "exp":1730937600, "entitlements":[], "views":[{ "bank_id":"nlbkb", "account_id":"95389297-45c4-40eb-9efd-331ba1943da4", "view_id":"ReadAccountsBerlinGroup" }], "access":{ "accounts":[{ "iban":"RS35260005601001611379" }] } }, "api_standard":"Berlin Group", "api_version":"v1.3" }] }
Required Roles:
  • CanGetConsentsAtOneBank - Please login to request this Role
  • CanGetConsentsAtAnyBank - 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: OBPv5.1.0, function_name: by getConsentsAtBank, operation_id: OBPv5.1.0-getConsentsAtBank Tags: Consent, Account Information Service (AIS), PSD2,

Get My Consents

This endpoint gets the Consents created by a current User.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

api_standard: api_standard

api_version:

consent_id:

consents:

jwt:

status:

Typical Successful Response:

								
									
{ "consents":[{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"INITIATED", "api_standard":"Berlin Group", "api_version":"v1.3" }] }
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.
Connector Methods:
Version: OBPv5.1.0, function_name: by getMyConsents, operation_id: OBPv5.1.0-getMyConsents Tags: Consent, Account Information Service (AIS), PSD2,

Get My Consents Info

This endpoint gets the Consents that the current User created.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

JSON response body fields:

api_standard: api_standard

api_version:

consent_id:

consents:

consumer_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

created_by_user_id:

last_action_date: last_action_date

last_usage_date: last_usage_date

status:

Typical Successful Response:

								
									
{ "consents":[{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "consumer_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "last_action_date":"2020-01-27", "last_usage_date":"2021-04-08T09:12:27Z", "status":"INITIATED", "api_standard":"Berlin Group", "api_version":"v1.3" }] }
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.
Connector Methods:
Version: OBPv4.0.0, function_name: by getConsentInfos, operation_id: OBPv4.0.0-getConsentInfos Tags: Consent, Account Information Service (AIS), PSD2,

Provide client's certificate info of a current call

Provide client's certificate info of a current call specified by PSD2-CERT value at Request Header

Authentication is Mandatory

JSON response body fields:

issuer_domain_name: issuer_domain_name

not_after: not_after

not_before: not_before

subject_domain_name: subject_domain_name

roles: CanCreateMyUser

roles_info: roles_info

Typical Successful Response:

								
									
{ "subject_domain_name":"OID.2.5.4.41=VPN, EMAILADDRESS=admin@tesobe.com, CN=TESOBE CA, OU=TESOBE Operations, O=TESOBE, L=Berlin, ST=Berlin, C=DE", "issuer_domain_name":"CN=localhost, O=TESOBE GmbH, ST=Berlin, C=DE", "not_before":"2022-04-01T10:13:00.000Z", "not_after":"2032-04-01T10:13:00.000Z", "roles_info":"PEM Encoded Certificate does not contain PSD2 roles." }
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.
Connector Methods:
Version: OBPv5.1.0, function_name: by mtlsClientCertificateInfo, operation_id: OBPv5.1.0-mtlsClientCertificateInfo Tags: Consent, Account Information Service (AIS), PSD2,

Revoke Consent

Revoke Consent for current user specified by CONSENT_ID

There are a few reasons you might need to revoke an application’s access to a user’s account:
- The user explicitly wishes to revoke the application’s access
- You as the service provider have determined an application is compromised or malicious, and want to disable it
- etc.

Please note that this endpoint only supports the case:: "The user explicitly wishes to revoke the application’s access"

OBP as a resource server stores access tokens in a database, then it is relatively easy to revoke some token that belongs to a particular user.
The status of the token is changed to "REVOKED" so the next time the revoked client makes a request, their token will fail to validate.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

CONSENT_ID:

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"REJECTED" }
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.
Connector Methods:
Version: OBPv3.1.0, function_name: by revokeConsent, operation_id: OBPv3.1.0-revokeConsent Tags: Consent, Account Information Service (AIS), PSD2,

Revoke Consent at Bank

Revoke Consent specified by CONSENT_ID

There are a few reasons you might need to revoke an application’s access to a user’s account:
- The user explicitly wishes to revoke the application’s access
- You as the service provider have determined an application is compromised or malicious, and want to disable it
- etc.

OBP as a resource server stores access tokens in a database, then it is relatively easy to revoke some token that belongs to a particular user.
The status of the token is changed to "REVOKED" so the next time the revoked client makes a request, their token will fail to validate.

Authentication is Mandatory

URL Parameters:

BANK_ID: gh.29.uk

CONSENT_ID:

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"REJECTED" }
Required Roles:
  • CanRevokeConsentAtBank - 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: OBPv5.1.0, function_name: by revokeConsentAtBank, operation_id: OBPv5.1.0-revokeConsentAtBank Tags: Consent, Account Information Service (AIS), PSD2,

Revoke Consent used in the Current Call

Revoke Consent specified by Consent-Id at Request Header

There are a few reasons you might need to revoke an application’s access to a user’s account:
- The user explicitly wishes to revoke the application’s access
- You as the service provider have determined an application is compromised or malicious, and want to disable it
- etc.

OBP as a resource server stores access tokens in a database, then it is relatively easy to revoke some token that belongs to a particular user.
The status of the token is changed to "REVOKED" so the next time the revoked client makes a request, their token will fail to validate.

Authentication is Mandatory

JSON response body fields:

consent_id:

jwt:

status:

Typical Successful Response:

								
									
{ "consent_id":"9d429899-24f5-42c8-8565-943ffa6a7945", "jwt":"eyJhbGciOiJIUzI1NiJ9.eyJlbnRpdGxlbWVudHMiOltdLCJjcmVhdGVkQnlVc2VySWQiOiJhYjY1MzlhOS1iMTA1LTQ0ODktYTg4My0wYWQ4ZDZjNjE2NTciLCJzdWIiOiIyMWUxYzhjYy1mOTE4LTRlYWMtYjhlMy01ZTVlZWM2YjNiNGIiLCJhdWQiOiJlanpuazUwNWQxMzJyeW9tbmhieDFxbXRvaHVyYnNiYjBraWphanNrIiwibmJmIjoxNTUzNTU0ODk5LCJpc3MiOiJodHRwczpcL1wvd3d3Lm9wZW5iYW5rcHJvamVjdC5jb20iLCJleHAiOjE1NTM1NTg0OTksImlhdCI6MTU1MzU1NDg5OSwianRpIjoiMDlmODhkNWYtZWNlNi00Mzk4LThlOTktNjYxMWZhMWNkYmQ1Iiwidmlld3MiOlt7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAxIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifSx7ImFjY291bnRfaWQiOiJtYXJrb19wcml2aXRlXzAyIiwiYmFua19pZCI6ImdoLjI5LnVrLngiLCJ2aWV3X2lkIjoib3duZXIifV19.8cc7cBEf2NyQvJoukBCmDLT7LXYcuzTcSYLqSpbxLp4", "status":"REJECTED" }
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.
Connector Methods:
Version: OBPv5.1.0, function_name: by selfRevokeConsent, operation_id: OBPv5.1.0-selfRevokeConsent Tags: Consent, Account Information Service (AIS), PSD2,

Get Counterparties (Explicit)

Get the Counterparties that have been explicitly created on the specified Account / View.

For a general introduction to Counterparties in OBP, see here

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

bespoke:

counterparties:

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

created_by_user_id:

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

is_beneficiary: false

key: CustomerNumber

name: ACCOUNT_MANAGEMENT_FEE

other_account_routing_address:

other_account_routing_scheme:

other_account_secondary_routing_address:

other_account_secondary_routing_scheme:

other_bank_routing_address:

other_bank_routing_scheme:

other_branch_routing_address:

other_branch_routing_scheme:

this_account_id:

this_bank_id:

this_view_id:

value: 5987953

Typical Successful Response:

								
									
{ "counterparties":[{ "name":"CounterpartyName", "description":"My landlord", "currency":"EUR", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }] }] }
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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • OBP-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getExplicitCounterpartiesForAccount, operation_id: OBPv4.0.0-getExplicitCounterpartiesForAccount Tags: Counterparty, Payment Initiation Service (PIS), PSD2, Account,

Get Counterparties for any account (Explicit)

This is a management endpoint that gets the Counterparties that have been explicitly created for an Account / View.

For a general introduction to Counterparties in OBP, see here

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

bespoke:

counterparties:

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

created_by_user_id:

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

is_beneficiary: false

key: CustomerNumber

name: ACCOUNT_MANAGEMENT_FEE

other_account_routing_address:

other_account_routing_scheme:

other_account_secondary_routing_address:

other_account_secondary_routing_scheme:

other_bank_routing_address:

other_bank_routing_scheme:

other_branch_routing_address:

other_branch_routing_scheme:

this_account_id:

this_bank_id:

this_view_id:

value: 5987953

Typical Successful Response:

								
									
{ "counterparties":[{ "name":"CounterpartyName", "description":"My landlord", "currency":"EUR", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }] }] }
Required Roles:
  • CanGetCounterparties - Please login to request this Role
  • CanGetCounterpartiesAtAnyBank - 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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-50000: Unknown Error.
  • OBP-20006: User is missing one or more roles:
Connector Methods:
Version: OBPv4.0.0, function_name: by getCounterpartiesForAnyAccount, operation_id: OBPv4.0.0-getCounterpartiesForAnyAccount Tags: Counterparty, Payment Initiation Service (PIS), PSD2, Account,

Get Counterparty by Id (Explicit)

This endpoint returns a single Counterparty on an Account View specified by its COUNTERPARTY_ID:

For a general introduction to Counterparties in OBP, see here

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

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

VIEW_ID: owner

JSON response body fields:

bespoke:

corporate_location: 10

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

created_by_user_id:

currency: EUR

date: 2020-01-27

description: Description of the object. Maximum length is 2000. It can be any characters here.

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

image_url:

is_beneficiary: false

key: CustomerNumber

latitude: 38.8951

longitude: -77.0364

metadata:

more_info: More information about this fee

name: ACCOUNT_MANAGEMENT_FEE

open_corporates_url:

other_account_routing_address:

other_account_routing_scheme:

other_account_secondary_routing_address:

other_account_secondary_routing_scheme:

other_bank_routing_address:

other_bank_routing_scheme:

other_branch_routing_address:

other_branch_routing_scheme:

physical_location:

private_alias:

provider: ETHEREUM

public_alias:

this_account_id:

this_bank_id:

this_view_id:

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

user:

username: felixsmith

value: 5987953

Typical Successful Response:

								
									
{ "name":"CounterpartyName", "description":"My landlord", "currency":"EUR", "created_by_user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1", "this_bank_id":"gh.29.uk", "this_account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0", "this_view_id":"owner", "counterparty_id":"9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh", "other_bank_routing_scheme":"OBP", "other_bank_routing_address":"gh.29.uk", "other_branch_routing_scheme":"OBP", "other_branch_routing_address":"12f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_routing_scheme":"OBP", "other_account_routing_address":"36f8a9e6-c2b1-407a-8bd0-421b7119307e", "other_account_secondary_routing_scheme":"IBAN", "other_account_secondary_routing_address":"DE89370400440532013000", "is_beneficiary":true, "bespoke":[{ "key":"englishName", "value":"english Name" }], "metadata":{ "public_alias":"String", "more_info":"String", "url":"String", "image_url":"String", "open_corporates_url":"String", "corporate_location":{ "latitude":11.45, "longitude":11.45, "date":"1100-01-01T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "physical_location":{ "latitude":11.45, "longitude":11.45, "date":"1100-01-01T00:00:00Z", "user":{ "id":"123", "provider":"http://127.0.0.1:8080", "username":"felixsmith" } }, "private_alias":"String" } }
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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getExplicitCounterpartyById, operation_id: OBPv4.0.0-getExplicitCounterpartyById Tags: Counterparty, Payment Initiation Service (PIS), PSD2, Counterparty-Metadata,

Get Transactions for Account (Core)

Returns transactions list (Core info) of the account specified by ACCOUNT_ID.

Authentication is Mandatory

Possible custom url parameters for pagination:

  • limit=NUMBER ==> default value: 50
  • offset=NUMBER ==> default value: 0

eg1:?limit=100&offset=0

  • sort_direction=ASC/DESC ==> default value: DESC.

eg2:?limit=100&offset=0&sort_direction=ASC

  • from_date=DATE => example value: 1970-01-01T00:00:00.000Z. NOTE! The default value is one year ago (1970-01-01T00:00:00.000Z).
  • to_date=DATE => example value: 2024-12-04T12:22:00.715Z. NOTE! The default value is now (2024-12-04T12:22:00.715Z).

Date format parameter: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'(1100-01-01T01:01:01.000Z) ==> time zone is UTC.

eg3:?sort_direction=ASC&limit=100&offset=0&from_date=1100-01-01T01:01:01.000Z&to_date=1100-01-01T01:01:01.000Z

URL Parameters:

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

BANK_ID: gh.29.uk

JSON response body fields:

account_routings:

address:

amount: 10.12

bank_routing:

completed: 2020-01-27

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

details:

holder:

holders:

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

is_alias:

name: ACCOUNT_MANAGEMENT_FEE

new_balance: 20

other_account:

posted: 2020-01-27

scheme: OBP

this_account:

transaction_attribute_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh

transaction_attributes:

transactions:

type:

value: 5987953

Typical Successful Response:

								
									
{ "transactions":[{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "this_account":{ "id":"String", "bank_routing":{ "scheme":"OBP", "address":"gh.29.uk" }, "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }], "holders":[{ "name":"OBP", "is_alias":true }] }, "other_account":{ "id":"5995d6a2-01b3-423c-a173-5481df49bdaf", "holder":{ "name":"OBP", "is_alias":true }, "bank_routing":{ "scheme":"OBP", "address":"gh.29.uk" }, "account_routings":[{ "scheme":"OBP", "address":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0" }] }, "details":{ "type":"AC", "description":"OBP", "posted":"1100-01-01T00:00:00Z", "completed":"1100-01-01T00:00:00Z", "new_balance":{ "currency":"EUR", "amount":"0" }, "value":{ "currency":"EUR", "amount":"0" } }, "transaction_attributes":[{ "transaction_attribute_id":"7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh", "name":"HOUSE_RENT", "type":"DATE_WITH_DAY", "value":"123456789" }] }] }
Validations:
  • Required JSON Validation: No
  • Allowed Authentication Types: Not set
Possible Errors:
  • OBP-10023: obp_sort_direction parameter can only take two values: DESC or ASC!
  • OBP-10024: wrong value for obp_offset parameter. Please send a positive integer (=>0)!
  • OBP-10025: wrong value for obp_limit parameter. Please send a positive integer (=>1)!
  • OBP-10026: Failed to parse date string. Please use this format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'!
  • 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-30005: View not found for Account. Please specify a valid value for VIEW_ID
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv3.0.0, function_name: by getCoreTransactionsForBankAccount, operation_id: OBPv3.0.0-getCoreTransactionsForBankAccount Tags: Transaction, Account Information Service (AIS), Account, PSD2,

Answer Transaction Request Challenge

In Sandbox mode, any string that can be converted to a positive integer will be accepted as an answer.

This endpoint totally depends on createTransactionRequest, it need get the following data from createTransactionRequest response body.

1)TRANSACTION_REQUEST_TYPE : is the same as createTransactionRequest request URL .

2)TRANSACTION_REQUEST_ID : is the id field in createTransactionRequest response body.

3) id : is challenge.id field in createTransactionRequest response body.

4) answer : must be 123 in case that Strong Customer Authentication method for OTP challenge is dummy.
For instance: SANDBOX_TAN_OTP_INSTRUCTION_TRANSPORT=dummy
Possible values are dummy,email and sms
In kafka mode, the answer can be got by phone message or other SCA methods.

Note that each Transaction Request Type can have its own OTP_INSTRUCTION_TRANSPORT method.
OTP_INSTRUCTION_TRANSPORT methods are set in Props. See sample.props.template for instructions.

Single or Multiple authorisations

OBP allows single or multi party authorisations.

Single party authorisation:

In the case that only one person needs to authorise i.e. answer a security challenge we have the following change of state of a transaction request:
INITIATED => COMPLETED

Multiparty authorisation:

In the case that multiple parties (n persons) need to authorise a transaction request i.e. answer security challenges, we have the followings state flow for a transaction request:
INITIATED => NEXT_CHALLENGE_PENDING => ... => NEXT_CHALLENGE_PENDING => COMPLETED

The security challenge is bound to a user i.e. in the case of a correct answer but the user is different than expected 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 the case REQUIRED_CHALLENGE_ANSWERS is not defined as an account attribute, the default number of security challenges created is one.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

TRANSACTION_REQUEST_ID: 8138a7e4-6d02-40e3-a129-0b2bf89de9f1

TRANSACTION_REQUEST_TYPE: SEPA

VIEW_ID: owner

JSON request body fields:

answer:

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

additional_information: additional_information

reason_code: reason_code

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:

challenge_type:

charge:

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

creditorAccount:

creditorName:

currency: EUR

date_of_birth: 2018-03-09

debtorAccount:

description: Description of the object. 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

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:

value: 5987953

to_agent: to_agent

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":"Description of the object. 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", "challenge":{ "id":"be1a183d-b301-4b83-b855-5eeffdd3526f", "allowed_attempts":3, "challenge_type":"SANDBOX_TAN" }, "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-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-40011: Transaction Request Status is not INITIATED.
  • OBP-40009: The TRANSACTION_REQUEST_TYPE has changed.
  • OBP-40014: Sorry, you've used up your allowed attempts.
  • OBP-00003: Transaction Requests is disabled in this API instance.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by answerTransactionRequestChallenge, operation_id: OBPv4.0.0-answerTransactionRequestChallenge Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

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://apiexplorer-ii-sandbox.openbankproject.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: Description of the object. 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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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,

Create Transaction Request (ACCOUNT_OTP)

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

ACCOUNT_OTP:

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: Description of the object. 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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestAccountOtp, operation_id: OBPv4.0.0-createTransactionRequestAccountOtp Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (AGENT_CASH_WITHDRAWAL)

Either the from or the to field must be filled. Those fields refers to the information about the party that will be refunded.

In case the from object is used, it means that the refund comes from the part that sent you a transaction.
In the from object, you have two choices :
- Use bank_id and account_id fields if the other account is registered on the OBP-API
- Use the counterparty_id field in case the counterparty account is out of the OBP-API

In case the to object is used, it means you send a request to a counterparty to ask for a refund on a previous transaction you sent.
(This case is not managed by the OBP-API and require an external adapter)

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

AGENT_CASH_WITHDRAWAL: AGENT_CASH_WITHDRAWAL

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON request body fields:

agent_number: 5987953

amount: 10.12

bank_id: gh.29.uk

charge_policy: SHARED

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

to:

value: 5987953

future_date: 20200127

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestAgentCashWithDrawal, operation_id: OBPv4.0.0-createTransactionRequestAgentCashWithDrawal Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (CARD)

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

Money goes into the Counterparty 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://apiexplorer-ii-sandbox.openbankproject.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:

CARD: CARD

JSON request body fields:

amount: 10.12

brand: Visa

card: card

card_number: 364435172576215

card_type: Credit

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

currency: EUR

cvv: 123

description: Description of the object. Maximum length is 2000. It can be any characters here.

expiry_month: 01

expiry_year: 2023

name_on_card: SusanSmith

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestCard, operation_id: OBPv4.0.0-createTransactionRequestCard Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (COUNTERPARTY)

Special instructions for COUNTERPARTY:

When using a COUNTERPARTY to create a Transaction Request, specificy the counterparty_id in the body of the request.
The routing details of the counterparty will be forwarded for the transfer.

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

COUNTERPARTY:

VIEW_ID: owner

JSON request body fields:

amount: 10.12

charge_policy: SHARED

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

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

to:

value: 5987953

future_date: 20200127

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestCounterparty, operation_id: OBPv4.0.0-createTransactionRequestCounterparty Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (REFUND)

Either the from or the to field must be filled. Those fields refers to the information about the party that will be refunded.

In case the from object is used, it means that the refund comes from the part that sent you a transaction.
In the from object, you have two choices :
- Use bank_id and account_id fields if the other account is registered on the OBP-API
- Use the counterparty_id field in case the counterparty account is out of the OBP-API

In case the to object is used, it means you send a request to a counterparty to ask for a refund on a previous transaction you sent.
(This case is not managed by the OBP-API and require an external adapter)

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

REFUND: REFUND

VIEW_ID: owner

JSON request body fields:

amount: 10.12

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

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

reason_code: reason_code

refund: refund

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

value: 5987953

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

bank_id: gh.29.uk

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

from:

to:

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestRefund, operation_id: OBPv4.0.0-createTransactionRequestRefund Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (SANDBOX_TAN)

When using SANDBOX_TAN, 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.

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 succeeed and thus result in a Transaction.

A Transaction Request might create a security challenge that needs to be answered before the Transaction Request proceeds.

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

{
"XAF":{
"XAF":1.0,
"HKD":0.0135503,
"AUD":0.00228226,
"KRW":1.87975,
"JOD":0.00127784,
"GBP":0.00131092,
"MXN":0.0396,
"AED":0.00601555,
"INR":0.110241,
"XBT":2.9074795E-8,
"JPY":0.185328,
"USD":0.00163773,
"ILS":0.00641333,
"EUR":0.00152449
},
"HKD":{
"XAF":73.8049,
"HKD":1.0,
"AUD":0.178137,
"KRW":143.424,
"JOD":0.0903452,
"GBP":0.0985443,
"MXN":2.8067,
"AED":0.467977,
"INR":9.09325,
"XBT":2.164242461E-6,
"JPY":14.0867,
"USD":0.127427,
"ILS":0.460862,
"EUR":0.112495
},
"AUD":{
"XAF":438.162,
"HKD":5.61346,
"AUD":1.0,
"KRW":895.304,
"JOD":0.556152,
"GBP":0.609788,
"MXN":16.0826,
"AED":2.88368,
"INR":50.4238,
"XBT":1.2284055924E-5,
"JPY":87.0936,
"USD":0.785256,
"ILS":2.83558,
"EUR":0.667969
},
"KRW":{
"XAF":0.531986,
"HKD":0.00697233,
"AUD":0.00111694,
"KRW":1.0,
"JOD":6.30634E-4,
"GBP":6.97389E-4,
"MXN":0.0183,
"AED":0.00320019,
"INR":0.0586469,
"XBT":1.4234725E-8,
"JPY":0.0985917,
"USD":8.7125E-4,
"ILS":0.00316552,
"EUR":8.11008E-4
},
"JOD":{
"XAF":782.572,
"HKD":11.0687,
"AUD":1.63992,
"KRW":1585.68,
"JOD":1.0,
"GBP":1.06757,
"MXN":30.8336,
"AED":5.18231,
"INR":90.1236,
"XBT":2.3803244006E-5,
"JPY":156.304,
"USD":1.41112,
"ILS":5.02018,
"EUR":0.237707
},
"GBP":{
"XAF":762.826,
"HKD":10.1468,
"AUD":1.63992,
"KRW":1433.92,
"JOD":0.936707,
"GBP":1.0,
"MXN":29.242,
"AED":4.58882,
"INR":84.095,
"XBT":2.2756409956E-5,
"JPY":141.373,
"USD":1.2493,
"ILS":4.7002,
"EUR":1.16278
},
"MXN":{
"XAF":25.189,
"HKD":0.3562,
"AUD":0.0621,
"KRW":54.4512,
"JOD":0.0324,
"GBP":0.0341,
"MXN":1.0,
"AED":0.1688,
"INR":3.3513,
"XBT":8.1112586E-7,
"JPY":4.8687,
"USD":0.0459,
"ILS":0.1541,
"EUR":0.0384
},
"AED":{
"XAF":166.236,
"HKD":2.13685,
"AUD":0.346779,
"KRW":312.482,
"JOD":0.1930565,
"GBP":0.217921,
"MXN":5.9217,
"AED":1.0,
"INR":18.3255,
"XBT":4.603349217E-6,
"JPY":30.8081,
"USD":0.27225,
"ILS":0.968033,
"EUR":0.253425
},
"INR":{
"XAF":9.07101,
"HKD":0.109972,
"AUD":0.0198319,
"KRW":17.0512,
"JOD":0.0110959,
"GBP":0.0118913,
"MXN":0.2983,
"AED":0.0545671,
"INR":1.0,
"XBT":2.2689396E-7,
"JPY":1.68111,
"USD":0.0148559,
"ILS":0.0556764,
"EUR":0.0138287
},
"XBT":{
"XAF":3.4353824E7,
"HKD":460448.9,
"AUD":81168.603,
"KRW":7.0131575E7,
"JOD":41960.111,
"GBP":44188.118,
"MXN":1230503.3,
"AED":217414.47,
"INR":4407607.74,
"XBT":1.0,
"JPY":6805170.8,
"USD":59245.918,
"ILS":182981.21,
"EUR":52436.431
},
"JPY":{
"XAF":5.39585,
"HKD":0.0709891,
"AUD":0.0114819,
"KRW":10.1428,
"JOD":0.00639777,
"GBP":0.0070735,
"MXN":0.2053,
"AED":0.032459,
"INR":0.594846,
"XBT":1.47171931E-7,
"JPY":1.0,
"USD":0.00883695,
"ILS":0.0320926,
"EUR":0.00822592
},
"USD":{
"XAF":610.601,
"HKD":7.84766,
"AUD":1.27347,
"KRW":1147.78,
"JOD":0.708659,
"GBP":0.800446,
"MXN":21.748,
"AED":3.6731,
"INR":67.3135,
"XBT":1.69154E-5,
"JPY":113.161,
"USD":1.0,
"ILS":3.55495,
"EUR":0.930886
},
"ILS":{
"XAF":155.925,
"HKD":2.16985,
"AUD":0.352661,
"KRW":315.903,
"JOD":0.199196,
"GBP":0.212763,
"MXN":6.4871,
"AED":1.03302,
"INR":17.9609,
"XBT":5.452272147E-6,
"JPY":31.1599,
"USD":0.281298,
"ILS":1.0,
"EUR":1.19318
},
"EUR":{
"XAF":655.957,
"HKD":8.88926,
"AUD":1.49707,
"KRW":1233.03,
"JOD":0.838098,
"GBP":0.860011,
"MXN":26.0359,
"AED":3.94594,
"INR":72.3136,
"XBT":1.9087905636E-5,
"JPY":121.567,
"USD":1.07428,
"ILS":4.20494,
"EUR":1.0
}
}

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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

SANDBOX_TAN:

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: Description of the object. 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:

challenge_type:

charge:

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

creditorAccount:

creditorName:

currency: EUR

date_of_birth: 2018-03-09

debtorAccount:

description: Description of the object. 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

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:

value: 5987953

to_agent: to_agent

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":"Description of the object. 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", "challenge":{ "id":"be1a183d-b301-4b83-b855-5eeffdd3526f", "allowed_attempts":3, "challenge_type":"SANDBOX_TAN" }, "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-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-30005: View not found for Account. Please specify a valid value for VIEW_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-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • 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: OBPv2.1.0, function_name: by createTransactionRequestSandboxTan, operation_id: OBPv2.1.0-createTransactionRequestSandboxTan Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (SEPA)

Special instructions for SEPA:

When using a SEPA Transaction Request, you specify the IBAN of a Counterparty in the body of the request.
The routing details (IBAN) of the counterparty will be forwarded to the core banking system for the transfer.

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

SEPA:

VIEW_ID: owner

JSON request body fields:

amount: 10.12

charge_policy: SHARED

code: 125

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

iban: DE91 1000 0000 0123 4567 89

to:

value: 5987953

amount: 10.12

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

document_number:

future_date: 20200127

reasons:

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestSepa, operation_id: OBPv4.0.0-createTransactionRequestSepa Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Create Transaction Request (SIMPLE)

Special instructions for SIMPLE:

You can transfer money to the Bank Account Number or IBAN directly.

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://apiexplorer-ii-sandbox.openbankproject.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_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0

BANK_ID: gh.29.uk

SIMPLE: SIMPLE

VIEW_ID: owner

JSON request body fields:

amount: 10.12

charge_policy: SHARED

currency: EUR

description: Description of the object. Maximum length is 2000. It can be any characters here.

name: ACCOUNT_MANAGEMENT_FEE

other_account_routing_address:

other_account_routing_scheme:

other_account_secondary_routing_address:

other_account_secondary_routing_scheme:

other_bank_routing_address:

other_bank_routing_scheme:

other_branch_routing_address:

other_branch_routing_scheme:

to:

value: 5987953

future_date: 20200127

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: Description of the object. 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_agent: to_agent

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":"Description of the object. 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 createTransactionRequestSimple, operation_id: OBPv4.0.0-createTransactionRequestSimple Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Get Transaction Request

Returns transaction request for transaction specified by TRANSACTION_REQUEST_ID and for account specified by ACCOUNT_ID at bank specified by BANK_ID.

The VIEW_ID specified must be 'owner' and the user must have access to this view.

Version 2.0.0 now returns charge information.

Transaction Requests serve to initiate transactions that may or may not proceed. They contain information including:

  • Transaction Request Id
  • Type
  • Status (INITIATED, COMPLETED)
  • Challenge (in order to confirm the request)
  • From Bank / Account
  • Details including Currency, Value, Description and other initiation information specific to each type. (Could potentialy include a list of future transactions.)
  • Related Transactions

PSD2 Context: PSD2 requires transparency of charges to the customer.
This endpoint provides the charge that would be applied if the Transaction Request proceeds - and a record of that charge there after.
The customer can proceed with the Transaction by answering the security challenge.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

TRANSACTION_REQUEST_ID: 8138a7e4-6d02-40e3-a129-0b2bf89de9f1

VIEW_ID: owner

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:

challenge_type:

charge:

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

creditorAccount:

creditorName:

currency: EUR

date_of_birth: 2018-03-09

debtorAccount:

description: Description of the object. 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

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:

value: 5987953

to_agent: to_agent

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":"Description of the object. 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", "challenge":{ "id":"be1a183d-b301-4b83-b855-5eeffdd3526f", "allowed_attempts":3, "challenge_type":"SANDBOX_TAN" }, "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-30001: Bank not found. Please specify a valid value for BANK_ID.
  • OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
  • OBP-20017: Current user does not have access to the view. Please specify a valid value for VIEW_ID.
  • OBP-60010: Get Transaction Requests Exception.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv4.0.0, function_name: by getTransactionRequest, operation_id: OBPv4.0.0-getTransactionRequest Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,

Get Transaction Request Types for Account

Returns the Transaction Request Types that the account specified by ACCOUNT_ID and view specified by VIEW_ID has access to.

These are the ways this API Server can create a Transaction via a Transaction Request
(as opposed to Transaction Types which include external types too e.g. for Transactions created by core banking etc.)

A Transaction Request Type internally determines:

  • the required Transaction Request 'body' i.e. fields that define the 'what' and 'to' of a Transaction Request,
  • the type of security challenge that may be be raised before the Transaction Request proceeds, and
  • the threshold of that challenge.

For instance in a 'SANDBOX_TAN' Transaction Request, for amounts over 1000 currency units, the user must supply a positive integer to complete the Transaction Request and create a Transaction.

This approach aims to provide only one endpoint for initiating transactions, and one that handles challenges, whilst still allowing flexibility with the payload and internal logic.

Authentication is Mandatory

URL Parameters:

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

BANK_ID: gh.29.uk

VIEW_ID: owner

JSON response body fields:

amount: 10.12

charge:

currency: EUR

summary:

transaction_request_types:

value: 5987953

Typical Successful Response:

								
									
{ "transaction_request_types":[{ "value":"10", "charge":{ "summary":"The bank fixed charge", "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-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.
  • Please specify a valid value for CURRENCY of your Bank Account.
  • Current user does not have access to the view
  • account not found at bank
  • user does not have access to owner view
  • OBP-40018: Sorry, Transaction Requests are not enabled in this API instance.
  • OBP-50000: Unknown Error.
Connector Methods:
Version: OBPv1.4.0, function_name: by getTransactionRequestTypes, operation_id: OBPv1.4.0-getTransactionRequestTypes Tags: Transaction-Request, Payment Initiation Service (PIS), PSD2,