Usage Guide

This document explains how to load the Dominican Republic SB Data Dictionary into the IFC OBP Sandbox and query it.

Python Scripts are provided which read the spreadsheets and call the OBP APIs.

Configure the script

We need to copy the script config and modify it - and add our username / password and consumer key.

1. cp ./obp_python/example_config.py to ./obp_python/config.py
2. add your username / password and consumer key

Copy your data set to the data sheet

We need to copy the spreadsheet template and then add your own data. Please do not change the structure of the spreadsheet in any way.

1. cp resources/sb_import_template.xlsx to resources/sb_import.xlsx
2. import your data set into the spreadsheet resources/sb_import.xlsx_

Use the script

We need to import the data and check it loaded ok. We can also remove the data.

1. To import data: run upload_data_set_to_sandbox.py

2. To check imported data: run get_imported_data_from_sandbox.py Note: sb data set productos are account attributes within obp accounts

3. To delete imported data: run delete_imported_data_from_sandbox.py

Endpoints for retrieving the data

There are multiple endpoints you can use to inspect and update the data. Here we list a basic set.

You need to be authenticated and authorised before you can call most of the endpoints.

The simplest way to authenticate is via Direct Login. You can also try the endpoints in API Explorer. API Explorer will tell you if you need a Role and you can request it on API Explorer by clicking a button there. Please contact support in case you need a Role.

Get Direct Login Token

For development purposes, you could use an easy access authentication, called direct login: Register your username and password here Get your consumer key here

Example (replace $YOUR_CONSUMER_KEY with your consumer key, not consumer secret):

curl --location --request POST 'https://ifcsandbox.openbankproject.com/my/logins/direct' \
--header 'Authorization: DirectLogin username="YOURUSERNAME",password="password",consumer_key=$YOUR_CONSUMER_KEY' \
--header 'Content-Type: application/json' 

Replace $YOUR_DIRECT_LOGIN_TOKEN in the Examples below with the token you get!

Get Bank

Use Endpoint Get Bank

Example:

curl --location --request GET 'https://ifcsandbox.openbankproject.com/obp/v5.0.0/banks/ADOPEM'

Get Customers

Use Endpoint Get Customers at Bank

Example:

curl --location --request GET 'https://ifcsandbox.openbankproject.com//obp/v5.0.0/banks/ADOPEM/customers' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN'

Get Customer by CustomerNumber

Use Endpoint Get Customer by CustomerNumber

Example:

curl --location --request POST 'https://ifcsandbox.openbankproject.com/obp/v4.0.0/banks/ADOPEM/customers/customer-number' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{  "customer_number":"4578102"}'

Get all accounts for one Bank

Use Endpoint Get Fast Firehose Accounts at Bank. Take a look at the documentation regarding the pagination

Example:

curl --location --request GET 'https://ifcsandbox.openbankproject.com//obp/v5.0.0/management/banks/ADOPEM/fast-firehose/accounts?limit=100&offset=0' \
--header 'Authorization: DirectLogin token=$YOUR_TOKEN' 

Get Account by AccountRouting

Use this Endpoint Get Account by AccountRouting

Example

curl --location --request POST 'https://ifcsandbox.openbankproject.com/obp/v5.0.0/management/accounts/account-routing-query' \
--header 'Content-Type: application/json' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN' \
--data-raw '{
    "bank_id": "ADOPEM",
    "account_routing": {
        "scheme": "account_number",
        "address": "50000210007693"
    }
}'

Get Branches for a Bank

curl --location --request GET 'https://ifcsandbox.openbankproject.com/obp/v3.0.0/banks/ADOPEM/branches' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN' \
--header 'Content-Type: application/json'

Get Authority Data Requests

Use the Endpoint Get Authority Data Request List

Technically, each bank has its own endpoint, but those only differ in the BANK_ID. Example:

curl --location --request GET 'https://ifcsandbox.openbankproject.com//obp/dynamic-entity/banks/POPULAR/authority_data_request' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN' 

Get Customer Overview

Use the endpoint Get Customer Overview Flat to get all relavent information of a customer by their Customer Number.

Example:

curl --location --request POST 'https://ifcsandbox.openbankproject.com//obp/v5.0.0/banks/ADOPEM/customers/customer-number-query/overview-flat' \
--header 'Authorization: DirectLogin token=$YOUR_DIRECT_LOGIN_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customer_number": "4578102"

Endpoints for uploading the data

If you are interested in the scripts underlying api endpoints, or even creating your own upload scripts, follow the process below

Create bank

Use Endpoint create Bank to create your bank.

Needs role "CanCreateBank" on the sandbox. Will give you the role "CanCreateEntitlementAtOneBank" , so you can grant yourself all roles needed below here

Create customer

Use Endpoint Create Customer The OBP modell demands information that you do not have. So for creation, there is the need to add some default values. Those could be hidden in the responses by query parameter, though.

Example of minimal working create Customer:

curl --location --request POST 'https://ifcsandbox.openbankproject.com//obp/v5.0.0/banks/APAP/customers' \
--header 'Authorization: DirectLogin token=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "legal_name": "Herbert Muller",
    "mobile_phone_number": "",
    "email": "",
    "face_image": {
        "url": "",
        "date": "1100-01-01T00:00:00Z"
    },
    "date_of_birth": "1100-01-01T00:00:00Z",
    "relationship_status": "",
    "dependants": 0,
    "dob_of_dependants": [
    ],
    "credit_rating": {
        "rating": "",
        "source": ""
    },
    "credit_limit": {
        "currency": "",
        "amount": ""
    },
    "highest_education_attained": "",
    "employment_status": "",
    "kyc_status": true,
    "last_ok_date": "1100-01-01T00:00:00Z",
    "title": "",
    "branch_id": "",
    "name_suffix": ""
}'

This call will create the customer_id needed for subsequent customer related apis. Needs role "CanCreateCustomer" for the bank (id), or "CanCreateCustomerAtAnyBank".

Create any bank specific customer attributes that you cannot map to obp generic attributes. Here Needs role "CanCreateCustomerAttributeAtOneBank" for the bank.

Update customer number

Use Endpoint Update the number of a Customer to change the automatically created Customernumber to the real value

Example:

curl --location --request PUT 'https://ifcsandbox.openbankproject.com//obp/v5.0.0/banks/APAP/customers/7uy8a7e4-6d02-40e3-a129-0b2bf89de8uh/number' \
--header 'Authorization: DirectLogin token=$YOUR_TOKEN' \
--header 'Content-Type: application/json' 
--data-raw '{
    "customer_number": "5987953"
}'

Accounts: If the product does not exist, create the Product

An account is of a certain product in obp ( like "Gold Card", "Generic Debit", "any_arbitrary_string"). If you want to add account attributes, which is what you want to do, you need to name a product for account creation (next step) Create here.

Needs role: "CanCreateProduct" at bank level or "CanCreateProductAtAnyBank".

Create the Account

Note that new created accounts must always have an balance of zero. So we need to make a initial transaction to/from the account to a settlement account create here

Example:

curl --location --request POST 'https://ifcsandbox.openbankproject.com/obp/v5.0.0/banks/APAP/accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: DirectLogin token=$YOUR_TOKEN' \
--data-raw '{
    "user_id": "",
    "label": "",
    "product_code": "Basic",
    "balance": {
        "currency": "DOP",
        "amount": "0"
    },
    "branch_id": "",
    "account_routings": [
        {
            "scheme": "account_number",
            "address": "799245353490933"
        }
    ]
}'

Needs role "CanCreateAccount" at bank level.

Create any bank specific account attributes that you cannot map to obp generic attributes. Here Needs role "CanCreateAccountAttributeAtOneBank" for the bank.

Create the settlement accounts

To make the initial transfer to set the balance, you will need a settlement account on the bank where this transaction goes to/ comes from. You will need one settlement account per currency.

Example:

curl --location --request POST 'https://ifcsandbox.openbankproject.com/obp/v5.0.0/banks/APAP/settlement-accounts' \
--header 'Content-Type: application/json' \
--header 'Authorization: DirectLogin token=$YOUR_TOKEN' \

--data-raw '{
    "user_id": "",
    "payment_system": "SANDBOX-TAN",
    "balance": {
        "currency": "DOP",
        "amount": "0"
    },
    "label": "",
    "branch_id": "",
    "account_routings": [
        {
            "scheme": "settlement",
            "address": "12345678"
        }
    ]
}'

Create the balance

Use Endpoint Create Historical Transactions to create a transaction from (positive balance) or from (negative balance) the settlement account. Settlement account_id will be: SANDBOX-TAN_SETTLEMENT_ACCOUNT_$CURRENCY <- replace $CURRENCY with the currency.

E.g. : SANDBOX-TAN_SETTLEMENT_ACCOUNT_DOP

Example:

curl --location --request POST 'https://ifcsandbox.openbankproject.com/obp/v5.0.0/banks/ADOPEM/management/historical/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: DirectLogin token=$YOUR_TOKEN' \
--data-raw '{
    "from_account_id": "SANDBOX-TAN_SETTLEMENT_ACCOUNT_DOP",
    "to_account_id": "6153fd73-c5c8-449f-8f2c-a360f4ee2f9f",
    "value": {
        "currency": "DOP",
        "amount": "2230"
    },
    "description": "this is for work",
    "posted": "1100-01-01T01:01:01Z",
    "completed": "1100-01-01T01:01:01Z",
    "type": "SANDBOX_TAN",
    "charge_policy": "SHARED"

Create Branch

Use Endpoint Create Branch Needs role "CanCreateBranch" at bank level or "CanCreateBranchAtAnyBank"

Create Authority Data Requests

Use Endpoint Create new Authority Data Request

Technically, each bank has its own endpoint, but those only differ in the BANK_ID.