-
Account
-
The thing that tokens of value (money) come in and out of. An account has one or more `owners` whichMore...
- Create Account (POST)
- Create Account Attribute
- Get Account by Id (Core)
-
-
Customer
-
The legal entity that has the relationship to the bank. Customers are linked to Users via `User CusMore...
- Add Social Media Handle
-
-
Dynamic Entity Manage
-
Dynamic Entities can be used to store and retrieve custom data objects (think your own tables andMore...
- Create Bank Level Dynamic Entity
- Get Bank Level Dynamic Entities
-
-
Transaction
-
Transactions are records of successful movements of value into or out of an `Account`. OBP TransacMore...
- Get Transactions for Account (Core)
-
v5.0.0 (17 APIs)
Create Account (POST)
Create Account at bank specified by BANK_ID.
The User can create an Account for himself - or - the User that has the USER_ID specified in the POST body.
If the POST body USER_ID is specified, the logged in user must have the Role CanCreateAccount. Once created, the Account will be owned by the User specified by USER_ID.
If the POST body USER_ID is not specified, the account will be owned by the logged in User.
The 'product_code' field SHOULD be a product_code from Product.
If the product_code matches a product_code from Product, account attributes will be created that match the Product Attributes.
Note: The Amount MUST be zero.
Authentication is Mandatory
URL Parameters:
- BANK_ID: gh.29.uk
JSON request body fields:
-
amount: 10.12
-
balance: 10
-
branch_id: DERBY6
-
currency: EUR
-
label: My Account
-
product_code: 1234
-
user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1
JSON response body fields:
-
account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
amount: 10.12
-
balance: 10
-
branch_id: DERBY6
-
currency: EUR
-
label: My Account
-
name: ACCOUNT_MANAGEMENT_FEE
-
product_code: 1234
-
user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1
-
value: 5987953
{
"account_id":"8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
"user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"label":"My Account",
"product_code":"1234",
"balance":{
"currency":"EUR",
"amount":"0"
},
"branch_id":"DERBY6",
"account_routings":[{
"scheme":"AccountNumber",
"address":"4930396"
}],
"account_attributes":[{
"product_code":"1234",
"account_attribute_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f",
"name":"OVERDRAFT_START_DATE",
"type":"DATE_WITH_DAY",
"value":"2012-04-23"
}]
}
-
CanCreateAccount
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-10001: Incorrect json format.
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-30106: Invalid Balance Amount.
- OBP-30112: Invalid Number. Initial balance must be a number, e.g 1000.00
- OBP-30109: Initial Balance of Account must be Zero (0).
- OBP-30105: Invalid Balance Currency.
- OBP-50000: Unknown Error.
Create Account Attribute
Create Account Attribute
Account Attributes are used to describe a financial Product with a list of typed key value pairs.
Each Account Attribute is linked to its Account by ACCOUNT_ID
Typical account attributes might be:
ISIN (for International bonds)
VKN (for German bonds)
REDCODE (markit short code for credit derivative)
LOAN_ID (e.g. used for Anacredit reporting)
ISSUE_DATE (When the bond was issued in the market)
MATURITY_DATE (End of life time of a product)
TRADABLE
See FPML for more examples.
The type field must be one of "STRING", "INTEGER", "DOUBLE" or DATE_WITH_DAY"
Authentication is Mandatory
URL Parameters:
-
ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
BANK_ID: gh.29.uk
-
PRODUCT_CODE: 1234
JSON request body fields:
JSON response body fields:
-
name: ACCOUNT_MANAGEMENT_FEE
-
product_code: 1234
-
value: 5987953
{
"product_code":"1234",
"account_attribute_id":"613c83ea-80f9-4560-8404-b9cd4ec42a7f",
"name":"OVERDRAFT_START_DATE",
"type":"DATE_WITH_DAY",
"value":"2012-04-23"
}
-
CanCreateAccountAttributeAtOneBank
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-10001: Incorrect json format.
- OBP-50000: Unknown Error.
- OBP-20006: User is missing one or more roles:
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:
{
"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":"AccountNumber",
"address":"4930396"
}],
"views_basic":["owner"]
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- 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.
Add Corporate Location to Counterparty
Add the geolocation of the counterparty's registered address
Authentication is Mandatory
URL Parameters:
-
ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
BANK_ID: gh.29.uk
-
VIEW_ID: owner
JSON request body fields:
JSON response body fields:
{
"success":"Success"
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- 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.
- the view does not allow metadata access
- the view does not allow adding a corporate location
- Coordinates not possible
- Corporate Location cannot be deleted
- OBP-50000: Unknown Error.
Add Counterparty More Info
Add a description of the counter party from the perpestive of the account e.g. My dentist
Authentication is Mandatory
URL Parameters:
-
ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
BANK_ID: gh.29.uk
-
VIEW_ID: owner
JSON request body fields:
JSON response body fields:
{
"success":"Success"
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-30018: Bank Account not found. Please specify valid values for BANK_ID and ACCOUNT_ID.
- OBP-10001: Incorrect json format.
- OBP-30022: The current view does not have the permission:
- the view ownerdoes not allow adding more info
- More Info cannot be added
- OBP-50000: Unknown Error.
Add Social Media Handle
Add a social media handle for the customer specified by CUSTOMER_ID
Authentication is Mandatory
URL Parameters:
-
BANK_ID: gh.29.uk
-
CUSTOMER_ID: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh
JSON request body fields:
- customer_number: 5987953
JSON response body fields:
{
"success":"Success"
}
-
CanAddSocialMediaHandle
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-10001: Incorrect json format.
- 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-20006: User is missing one or more roles:
- OBP-30046: Customer not found. Please specify a valid value for CUSTOMER_ID.
- OBP-50000: Unknown Error.
Create Bank Level Dynamic Entity
Create a Bank Level DynamicEntity.
Authentication is Mandatory
Create a DynamicEntity. If creation is successful, the corresponding POST, GET, PUT and DELETE (Create, Read, Update, Delete or CRUD for short) endpoints will be generated automatically
The following field types are as supported:
[number, integer, boolean, string, DATE_WITH_DAY, reference]
The DATE_WITH_DAY format is: yyyy-MM-dd
Reference types are like foreign keys and composite foreign keys are supported. The value you need to supply as the (composite) foreign key is a UUID (or several UUIDs in the case of a composite key) that match value in another Entity..
The following list shows all the possible reference types in the system with corresponding examples values so you can see how to construct each reference type value.
"someField0": {
"type": "reference:OBP_API",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField1": {
"type": "reference:FooBar",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField2": {
"type": "reference:OBP_Activity",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField3": {
"type": "reference:OBP_Reena",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField4": {
"type": "reference:Bank",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField5": {
"type": "reference:Consumer",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField6": {
"type": "reference:Customer",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField7": {
"type": "reference:MethodRouting",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField8": {
"type": "reference:DynamicEntity",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField9": {
"type": "reference:TransactionRequest",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField10": {
"type": "reference:ProductAttribute",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField11": {
"type": "reference:AccountAttribute",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField12": {
"type": "reference:TransactionAttribute",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField13": {
"type": "reference:CustomerAttribute",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField14": {
"type": "reference:AccountApplication",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField15": {
"type": "reference:CardAttribute",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField16": {
"type": "reference:Counterparty",
"example": "2e15080e-26f8-4e83-b8d6-ddc57663b010"
}
"someField17": {
"type": "reference:Branch:bankId&branchId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&branchId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4"
}
"someField18": {
"type": "reference:Atm:bankId&atmId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&atmId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4"
}
"someField19": {
"type": "reference:BankAccount:bankId&accountId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&accountId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4"
}
"someField20": {
"type": "reference:Product:bankId&productCode",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&productCode=9e7bc659-a721-4c95-994a-77ddb8ca2bf4"
}
"someField21": {
"type": "reference:PhysicalCard:bankId&cardId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&cardId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4"
}
"someField22": {
"type": "reference:Transaction:bankId&accountId&transactionId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&accountId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4&transactionId=d6b5f9ea-b7c1-48da-8697-25913c06175a"
}
"someField23": {
"type": "reference:Counterparty:bankId&accountId&counterpartyId",
"example": "bankId=2e15080e-26f8-4e83-b8d6-ddc57663b010&accountId=9e7bc659-a721-4c95-994a-77ddb8ca2bf4&counterpartyId=d6b5f9ea-b7c1-48da-8697-25913c06175a"
}
Note: BankId filed is optional,
if you add it, the entity will be the Bank level.
if you omit it, the entity will be the System level.
{
"bankId":"gh.29.uk",
"FooBar":{
"description":"description of this entity, can be markdown text.",
"required":["name"],
"properties":{
"name":{
"type":"string",
"minLength":3,
"maxLength":20,
"example":"James Brown",
"description":"description of **name** field, can be markdown text."
},
"number":{
"type":"integer",
"example":698761728,
"description":"description of **number** field, can be markdown text."
}
}
},
"dynamicEntityId":"dynamic-entity-id",
"userId":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"
}
-
CanCreateBankLevelDynamicEntity
- Please login to request this Role
-
CanCreateDynamicEntity
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-10001: Incorrect json format.
- OBP-50000: Unknown Error.
Get Bank Level Dynamic Entities
Get all the bank level Dynamic Entities for one bank.
Authentication is Mandatory
{
"dynamic_entities":[{
"bankId":"gh.29.uk",
"FooBar":{
"description":"description of this entity, can be markdown text.",
"required":["name"],
"properties":{
"name":{
"type":"string",
"minLength":3,
"maxLength":20,
"example":"James Brown",
"description":"description of **name** field, can be markdown text."
},
"number":{
"type":"integer",
"example":698761728,
"description":"description of **number** field, can be markdown text."
}
}
},
"dynamicEntityId":"dynamic-entity-id",
"userId":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1"
}]
}
-
CanGetBankLevelDynamicEntities
- Please login to request this Role
-
CanGetDynamicEntities
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
Create Fx
Create or Update Fx for the Bank.
Example:
“from_currency_code”:“EUR”,
“to_currency_code”:“USD”,
“conversion_value”: 1.136305,
“inverse_conversion_value”: 1 / 1.136305 = 0.8800454103431737,
Thus 1 Euro = 1.136305 US Dollar
and
1 US Dollar = 0.8800 Euro
Authentication is Mandatory
URL Parameters:
- BANK_ID: gh.29.uk
JSON response body fields:
-
bank_id: gh.29.uk
-
conversion_value: 100
-
effective_date: 2020-01-27
-
to_currency_code: EUR
{
"bank_id":"gh.29.uk",
"from_currency_code":"EUR",
"to_currency_code":"USD",
"conversion_value":1.136305,
"inverse_conversion_value":0.8800454103431737,
"effective_date":"2017-09-19T00:00:00Z"
}
-
CanCreateFxRate
- Please login to request this Role
-
CanCreateFxRateAtAnyBank
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
Get Current FxRate
Get the latest FX rate specified by BANK_ID, FROM_CURRENCY_CODE and TO_CURRENCY_CODE
OBP may try different sources of FX rate information depending on the Connector in operation.
For example we want to convert EUR => USD:
OBP will:
1st try - Connector (database, core banking system or external FX service)
2nd try part 1 - fallbackexchangerates/eur.json
2nd try part 2 - fallbackexchangerates/usd.json (the inverse rate is used)
3rd try - Hardcoded map of FX rates.
Authentication is Mandatory
URL Parameters:
-
BANK_ID: gh.29.uk
-
TO_CURRENCY_CODE: EUR
JSON response body fields:
-
bank_id: gh.29.uk
-
conversion_value: 100
-
effective_date: 2020-01-27
-
to_currency_code: EUR
{
"bank_id":"gh.29.uk",
"from_currency_code":"EUR",
"to_currency_code":"GBP",
"conversion_value":1.001,
"inverse_conversion_value":0.998,
"effective_date":"2017-09-19T00:00:00Z"
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-10003: Invalid Currency Value. It should be three letters ISO Currency Code.
- OBP-20001: User not logged in. Authentication is required!
- OBP-10004: ISO Currency code combination not supported for FX. Please modify the FROM_CURRENCY_CODE or TO_CURRENCY_CODE.
- OBP-50000: Unknown Error.
Add Asset To A Fund
Add an Asset to an existing fund
MethodRouting settings example:
{
"is_bank_id_exact_match":false,
"method_name":"dynamicEndpointProcess",
"connector_name":"rest_vMar2019",
"bank_id_pattern":".*",
"parameters":[
{
"key":"url_pattern",
"value":"https://play-api.qredo.network/api/v1/p/company/{company_id}/fund/{fund_id}/asset"
},
{
"key":"http_method",
"value":"POST"
}
{
"key":"url",
"value":"http://mydomain.com/xxx"
}
]
}
Authentication is Mandatory
{
"wallets":["string"]
}
-
CanCreateDynamicEndpoint_FundAsset567
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
Add Fund
Create a Fund that serves as a wallet containing assets, addresses, and custody policies. Custody policies for both deposits and withdrawals must exist for a fund. Policies can include multiple custodians, or a single user that self-manages custody. For an individual fund, you can also add whitelisted withdrawal addresses.
MethodRouting settings example:
{
"is_bank_id_exact_match":false,
"method_name":"dynamicEndpointProcess",
"connector_name":"rest_vMar2019",
"bank_id_pattern":".*",
"parameters":[
{
"key":"url_pattern",
"value":"https://play-api.qredo.network/api/v1/p/company/{company_id}/fund"
},
{
"key":"http_method",
"value":"POST"
}
{
"key":"url",
"value":"http://mydomain.com/xxx"
}
]
}
Authentication is Mandatory
{
"custodygroup_tx":"string",
"custodygroup_withdraw":"string",
"fund_id":"string"
}
-
CanCreateDynamicEndpoint_Fund114
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
Add Trusted Party
Add a Trusted Party for the Company. A Trusted Party is a user that can be added as a custodian of a wallet or member of a fund. Qredo network as a Company or User.
When adding a user, they must approve this via their Qredo Signing App.
MethodRouting settings example:
{
"is_bank_id_exact_match":false,
"method_name":"dynamicEndpointProcess",
"connector_name":"rest_vMar2019",
"bank_id_pattern":".*",
"parameters":[
{
"key":"url_pattern",
"value":"https://play-api.qredo.network/api/v1/p/company/{company_id}/trustedparty"
},
{
"key":"http_method",
"value":"POST"
}
{
"key":"url",
"value":"http://mydomain.com/xxx"
}
]
}
Authentication is Mandatory
{
"code":1,
"msg":"string"
}
-
CanCreateDynamicEndpoint_TrustedPartyNew113
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
Add Wallet To A Fund
Add a new Wallet to an existing fund. If Custody groups are blank the default fund cutosdy policy will be used
MethodRouting settings example:
{
"is_bank_id_exact_match":false,
"method_name":"dynamicEndpointProcess",
"connector_name":"rest_vMar2019",
"bank_id_pattern":".*",
"parameters":[
{
"key":"url_pattern",
"value":"https://play-api.qredo.network/api/v1/p/company/{company_id}/fund/{fund_id}/wallet"
},
{
"key":"http_method",
"value":"POST"
}
{
"key":"url",
"value":"http://mydomain.com/xxx"
}
]
}
Authentication is Mandatory
{
"wallets":["string"]
}
-
CanCreateDynamicEndpoint_FundWallet103
- Please login to request this Role
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-50000: Unknown Error.
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: 2022-02-04T00:00:42.636Z. NOTE! The default value is one year ago (2022-02-04T00:00:42.636Z).
- to_date=DATE => example value: 2023-02-04T00:00:42.636Z. NOTE! The default value is now (2023-02-04T00:00:42.636Z).
Date format parameter: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'(2017-09-19T02:31:05.000Z) ==> time zone is UTC.
eg3:?sort_direction=ASC&limit=100&offset=0&from_date=2017-09-19T02:31:05.000Z&to_date=2017-09-19T02:31:05.000Z
URL Parameters:
-
ACCOUNT_ID: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
BANK_ID: gh.29.uk
JSON response body fields:
-
amount: 10.12
-
completed: 2020-01-27
-
currency: EUR
-
description: This an optional field. Maximum length is 2000. It can be any characters here.
-
name: ACCOUNT_MANAGEMENT_FEE
-
new_balance: 20
-
posted: 2020-01-27
-
transaction_attribute_id: 7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh
-
value: 5987953
{
"transactions":[{
"id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
"this_account":{
"id":"String",
"bank_routing":{
"scheme":"Bank_ID",
"address":"gh.29.uk"
},
"account_routings":[{
"scheme":"AccountNumber",
"address":"4930396"
}],
"holders":[{
"name":"OBP",
"is_alias":true
}]
},
"other_account":{
"id":"5995d6a2-01b3-423c-a173-5481df49bdaf",
"holder":{
"name":"OBP",
"is_alias":true
},
"bank_routing":{
"scheme":"Bank_ID",
"address":"gh.29.uk"
},
"account_routings":[{
"scheme":"AccountNumber",
"address":"4930396"
}]
},
"details":{
"type":"AC",
"description":"OBP",
"posted":"2017-09-19T00:00:00Z",
"completed":"2017-09-19T00: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"
}]
}]
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- 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.
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:
-
additional_information: additional_information
-
reason_code: reason_code
JSON response body fields:
-
account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
amount: 10.12
-
bank_id: gh.29.uk
-
counterparty_id: 9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh
-
currency: EUR
-
date_of_birth: 2018-03-09
-
description: This an optional field. Maximum length is 2000. It can be any characters here.
-
future_date: 20200127
-
iban: DE91 1000 0000 0123 4567 89
-
instructedAmount: 100
-
legal_name: Eveline Tripman
-
[message](/glossary#Message Doc): 123456
-
name: ACCOUNT_MANAGEMENT_FEE
-
start_date: 2020-01-27
-
to_simple: to_simple
-
value: 5987953
{
"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_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":"String"
},
"transaction_ids":["902ba3bb-dedd-45e7-9319-2fd3f2cd98a1"],
"status":"COMPLETED",
"start_date":"2017-09-19T00:00:00Z",
"end_date":"2017-09-19T00: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"
}
}
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- 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.
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:
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
-
VIEW_ID: owner
JSON request body fields:
-
account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
amount: 10.12
-
bank_id: gh.29.uk
-
currency: EUR
-
description: This an optional field. Maximum length is 2000. It can be any characters here.
-
value: 5987953
JSON response body fields:
-
account_id: 8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0
-
amount: 10.12
-
bank_id: gh.29.uk
-
challenges: challenges
-
counterparty_id: 9fg8a7e4-6d02-40e3-a129-0b2bf89de8uh
-
currency: EUR
-
date_of_birth: 2018-03-09
-
description: This an optional field. Maximum length is 2000. It can be any characters here.
-
future_date: 20200127
-
iban: DE91 1000 0000 0123 4567 89
-
instructedAmount: 100
-
legal_name: Eveline Tripman
-
[message](/glossary#Message Doc): 123456
-
name: ACCOUNT_MANAGEMENT_FEE
-
start_date: 2020-01-27
-
to_simple: to_simple
-
user_id: 9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1
-
value: 5987953
{
"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_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":"String"
},
"transaction_ids":["902ba3bb-dedd-45e7-9319-2fd3f2cd98a1"],
"status":"COMPLETED",
"start_date":"2017-09-19T00:00:00Z",
"end_date":"2017-09-19T00:00:00Z",
"challenges":[{
"id":"2fg8a7e4-6d02-40e3-a129-0b2bf89de8ub",
"user_id":"9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"allowed_attempts":3,
"challenge_type":"OTP_VIA_API",
"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"
}
}
}
- Required JSON Validation: No
- Allowed Authentication Types: Not set
- 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 view don't have the `canAddTransactionRequestToAnyAccount` permission or your consumer doesn't not have the access to the view of the from account or you don't have the role CanCreateAnyTransactionRequest.
- 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.