➕Create New Bank Account

To complete a Customer Affordability Assessment, you will first need to create a Bank Account ID. Transactional Data as well as PDF Bank Statements collected from Customers are stored against

Create New Bank Account

POST {{baseUrl}}/bank-accounts

You will need to first save the customerId from the POST Create New Customer response as a variable to use in the request body for Create New Bank Account.

Path Parameters

Name	Type	Description
tenantId*	String	This is the tenantId that was assigned to you when your tenant was created.
environmentUrl*	String	Environment URL uat - https://uat.apply.fincheck.co.za prod - https://apply.fincheck.co.za

Request Body

Key	Value	Description
bank*	String	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 this list of slugs for the available banks.
type*	String	You can create either an "online", "statement" or "ussd" bank account. Please click here for more information.
customer_id*	String	This is UUID for a specific customer that gets generated and returned in the POST Create New Customer response. It ensures that the Bank Account is created and associated to a customer.
account_number	String	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 POST Bank Statement Upload V1.1.

Status Codes

201 - Created

Online Bank Account Created

{
    "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

{
    "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

{
    "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
    }
}

401 - Unauthorised

Unauthenticated

{
    "error": "Unauthenticated."
}

422 - Unprocessable Content

Invalid Bank

{
    "errors": {
        "bank": [
            "Provided bank is not valid. Please check list of supported banks."
        ]
    }
}

Invalid Type

{
    "errors": {
        "type": [
            "The selected type is invalid."
        ]
    }
}

Missing Parameter

{
    "errors": {
        "customer_id": [
            "The customer id field is required when business id is not present."
        ],
        "business_id": [
            "The business id field is required when customer id is not present."
        ]
    }
}

Syntax

{
    "errors": {
        "type": [
            "The type field is required."
        ],
        "bank": [
            "The bank field is required."
        ],
        "customer_id": [
            "The customer id field is required when business id is not present."
        ],
        "business_id": [
            "The business id field is required when customer id is not present."
        ]
    }
}

Key Variables

Bank

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.

Online

Accepted online bank slugs

• absa

• capitec

• discovery

• fnb

• nedbank

• standard-bank

• tyme-bank (Only extracts the data, no statements are downloaded)

Statement

Accepted statement bank slugs

• absa

• capitec

• discovery

• easypay

• fnb

• investec

• nedbank

• standard-bank

• rmb

• tyme-bank

USSD

Accepted USSD bank slugs

• capitec

• fnb

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:

• "online"

• "statement"

• "ussd"

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.

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.

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.

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.

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.

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 for a guide to help your customers navigate the "online" flow successfully.

Statement

Statements

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

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

• 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.

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.

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

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.

Disadvantages of USSD

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.

Examples

Request body | Example 1

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

Request body | Example 2

Only applicable when making use of Bank Statement Upload V1.1 to support the custom bank account number statement validation.

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

The next step would be to collect the transactional data for the bank account. This is where the process diverges, depending on whether the processing type was selected as "online", "statement", "ussd" in your Create new Bank Account request.