# Create New Bank Account

## Create New Bank Account

#### <mark style="color:orange;">`POST`</mark> `{{baseUrl}}/bank-accounts`

### Path Parameters

<table><thead><tr><th width="178">Name</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td>tenantId<mark style="color:red;">*</mark></td><td>String</td><td><p>This is the <code>tenantId</code> that was assigned to you when your tenant was created. You will have received this information via  message from a member of the Finch Technologies team. If you can't find it, please email </p><p><strong>support@finch-technologies.com.</strong></p></td></tr><tr><td>environmentUrl<mark style="color:red;">*</mark></td><td>String</td><td>*Please note that you need to be set up in each environment by a member of the Finch Technologies team, who will share your bearer token with you for the  specific environment in a protected link. </td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="177">Key</th><th width="109">Value</th><th>Description</th></tr></thead><tbody><tr><td>bank<mark style="color:red;">*</mark></td><td>String</td><td>This is the name of the bank that the end-user/customer banks with. Each bank has a "slug" which you will have to use here. Please see <a href="#bank">this list</a> of slugs for the available banks.</td></tr><tr><td>type<mark style="color:red;">*</mark></td><td>String</td><td>You can create either an "online", "statement" or "ussd" bank account. Please click <a href="#type">here</a> for more information.</td></tr><tr><td>customer_id</td><td>String</td><td>This is UUID for a specific customer that gets generated and returned in the <a href="../../customers/single-customer-crud/create-new-customer"><em><mark style="color:orange;"><strong>POST</strong></mark><strong> Create New Customer</strong></em> </a>response. It ensures that the Bank Account is created and associated to a customer. </td></tr><tr><td>account_number</td><td>String</td><td>This is the person's account number that appears on their bank statement. If a value is provided for this, we will run a validation that the account_number provided matched the Account Number that can be found on the statement before processing the upload in <a href="../bank-statement-upload/bank-statement-upload-v1.1"><em><mark style="color:orange;"><strong>POST</strong></mark><strong> </strong><strong>Bank Statement Upload V1.1</strong></em></a>.</td></tr><tr><td>create_customer</td><td>boolean</td><td>Determines whether a new customer record should be created during the online processing flow. If set to true, a new customer profile will be created automatically before initiating the online login session. If set to false, the request will attempt to start a session using an existing customer record. </td></tr></tbody></table>

### Example Request Body - Online&#x20;

{% hint style="success" %}
The next step would be to collect the transactional, account and statement data. &#x20;

#### [Sync Online Banking Accounts](https://finch-technologies.gitbook.io/gathr-api-documentation/online-login/sync-online-banking-accounts#get-baseurl-bank-accounts-bank_account_id-sync-redirect_url-redirecturl)

{% endhint %}

{% columns %}
{% column %}

#### With Customer Record

```json
{
    "bank": "fnb",
    "type": "online",
    //"account_number": "XXXXXXXXXXX",
    "customer_id": "{{customerId}}"
}
```

{% endcolumn %}

{% column %}

#### Without Customer Record

```json
{
    "bank": "fnb",
    "type": "online",
    //"account_number": "XXXXXXXXXXX",
    "create_customer": true
}
```

{% endcolumn %}
{% endcolumns %}

### Example Request Body - Statement&#x20;

{% hint style="success" %}
The next step would be to collect the transactional, account and statement data. &#x20;

#### [Upload Bank Statement V1.1 ](https://finch-technologies.gitbook.io/gathr-api-documentation/consumer-affordability-v1/bank-statement-upload/bank-statement-upload-v1.1)

{% endhint %}

{% columns %}
{% column %}

#### Example 1&#x20;

```json
{
    "bank": "absa",
    "type": "statement",
    "customer_id": "{{customerId}}"
}
```

{% endcolumn %}

{% column %}

#### Example 2

To support bank account number validation.&#x20;

```json
{
    "bank": "absa",
    "type": "statement",
    "account_number": "12345678", 
    "customer_id": "{{customerId}}"
}   
```

{% endcolumn %}
{% endcolumns %}

### Status Codes&#x20;

<details>

<summary>201 - Created </summary>

Online Bank Account Created&#x20;

```json
{
    "data": {
        "id": "{{$randomUUID}}",
        "customer_id": "{{customerId}}",
        "type": "online",
        "bank": "fnb",
        "num_transactions": 0,
        "last_updated": "2023-01-16T14:52:56.000000Z",
        "first_transaction": null,
        "last_transaction": null
    }
}
```

Statement Bank Account Created&#x20;

```json
{
    "data": {
         "id": "{{$randomUUID}}",
        "customer_id": "{{customerId}}",
        "type": "statement",
        "bank": "absa",
        "num_transactions": 0,
        "last_updated": "2023-04-24T12:50:47.000000Z",
        "first_transaction": null,
        "last_transaction": null
    }
}
```

USSD Bank Account Created&#x20;

```json
{
    "data": {
         "id": "{{$randomUUID}}",
        "customer_id": "{{customerId}}",
        "type": "ussd",
        "bank": "capitec",
        "num_transactions": 0,
        "last_updated": "2023-04-24T12:50:47.000000Z",
        "first_transaction": null,
        "last_transaction": null
    }
}
```

</details>

<details>

<summary>401 - Unauthorised</summary>

Unauthenticated&#x20;

```json
{
    "error": "Unauthenticated."
}
```

</details>

### Key Variables&#x20;

#### Bank&#x20;

The `"bank"`string determines the name of the bank that the end-user/customer banks with. It is advised that  `"bank"`is set to the bank that the end-user/customer receives their main source of income on.&#x20;

{% tabs %}
{% tab title="Online" %}
Accepted online bank slugs&#x20;

* absa
* capitec
* discovery
* fnb
* nedbank
* standard-bank
* tyme-bank (Only extracts the data, no statements are downloaded)
  {% endtab %}

{% tab title="Statement" %}
Accepted  statement bank slugs

* absa
* capitec
* discovery
* easypay
* fnb
* investec
* nedbank
* standard-bank
* rmb
* tyme-bank&#x20;
  {% endtab %}

{% tab title="USSD" %}
Accepted USSD bank slugs&#x20;

* capitec
* fnb
  {% endtab %}
  {% endtabs %}

#### Type

The `"type"` provided will determine the method used to collect transactional data as well as PDF bank statements. The `"type"` string can be either of the three options below:&#x20;

* "online"
* "statement"
* "ussd"&#x20;

{% tabs %}
{% tab title="Online" %}

### **Online**

The collection of transactional data as well as bank statements will be processed through an iFrame for the customer to login in to their online banking profile.&#x20;

**Advantages of Online**

The "online" method requires a lot less effort from the customer as they facilitate the login to their internet banking profile and select the account they want to glean data from. This is all done in a few simple clicks on our user-friendly journey through which the customer is guided on our GathrLink user interface.&#x20;

Gathr then handles the task of fetching the transactional data and downloading the statements. The customer does not have to worry about providing the correct bank statements as he collection of the bank statements is done automatically.&#x20;

In addition, the Gathr affordability service is able to collect transactional data from the internet banking website that might not yet be on the bank statement.

**Disadvantages of Online**

Surprisingly, the main pain point encountered in the Gathr Link online flow is the fact that the customer needs to know their internet banking login credentials and have access to their primary device to approve additional authentication requests.&#x20;

This sometimes results in human error when the customer is trying to login to their bank account, which stops the process from going ahead as we cannot scrape bank accounts without the user granting access/completing the authentication by logging in to their bank account.&#x20;

However, if the person is someone who is used to making online payments for example, they should be able to complete the process without much fuss. [See here](#online-login-guide-user-manual) for a guide to help your customers navigate the "online" flow successfully.&#x20;
{% endtab %}

{% tab title="Statement" %}

### Statements&#x20;

An alternative option would be if a set of valid PDF bank statements are available, the transactional data will be processed through manually uploading the documents .

Please [click here](https://finch-technologies.gitbook.io/gathr-api-documentation/consumer-affordability-v1/bank-statement-upload) to see more information on the types of statements you can upload.

**Advantages of Statement**

Provided the customer has already downloaded their bank statements, the "statement" method allows the customer to upload their PDF bank statement/s to their unique bank account Id.&#x20;

Statement upload method can serve as a handy fallback for cases where:

* The customer does not wish to enter their online banking credentials in the GathrLink iFrame
* &#x20;The customer does not know or cannot remember their password
* If there is a problem with the "online" method due to technical issues on our side or one of the banks' side. [See "online" monitoring dashboard here](https://finch-technologies.gitbook.io/gathr-api-documentation/welcome).

**Disadvantages of Statement**

The statement upload method requires the customer to upload valid PDF bank statements for the last 3 months. This can be as either a singular 3-month/6-month statement or as three individual/distinct 1-month statements.&#x20;
{% endtab %}

{% tab title="USSD" %}

### USSD

Leverage existing USSD infrastructure provided by banks to collect customers bank statements.  Using the customers mobile number that is registered to their bank account, a user can send their bank statements to our service for them to be digitized, categorized and stored.

**Advantages of USSD**&#x20;

Only 15% of South Africans have access to a banking app or online internet banking and by leveraging off the existing USSD infrastructure you are able to provide accessibility for mobile banking users (people who do not have online banking or app banking.&#x20;

**Disadvantages of USSD**&#x20;

The downside to this process is the reliance on the user to send their bank statements to a dedicated tenant e-mail account. If the statement is not sent to the correct email account, we are unable to associate the customer and process the bank statement. &#x20;
{% endtab %}
{% endtabs %}

### &#x20;