🔍Bank Identification Service

Using OCR technology we are able to identify the bank and statement template leading to enable bank statement parsing.

The Bank Identification Service enables the asynchronous process of creating thebank_account_id validating the document, processing and storing of transactions. This means we handle the Create new Bank Account api call.

Upload Bankstatement for Customer V1.1

POST{{environmentUrl}}/{{tenantId}}/api/v1.1/customers/{{customerId}}/upload-bankstatement

There is a maximum of 6 bank statements that can be uploaded in one API call.

Request Body

Key	Value	Description
statements[]*	form-data	Select the file/s you would like to upload. The file/files needs to be a valid bank PDF statement that the customer has downloaded from their internet banking. See here for more information on the types of statements that can be uploaded. There is a maximum of 6 bank statements that can be uploaded in one API call.
statement_result_url*	String	Add a value for this parameter to send the outcome of the statement processing. i.e. the URL to which you would like to receive the results of the successful, transaction processing. You can save the value in the environment variable {{StatementResultURL}}.
category_engine	String	To enable refined transaction categorisation you will need to set the category_engine to x-finch. For more information refer to the Transaction Categorisation page.

200 - OK

Statement Upload Successfully

{
    "data": [
        {
            "id": "{{$randomUUID}}",
            "bank_account_id": "{{bankAccountId}}",
            "statement_date": "2023-03-28",
            "start_date": "2023-02-28",
            "end_date": "2023-03-28",
            "temp_url": "https://fincheck-onboarding.s3.eu-west-1.amazonaws.com/production/client_e5354855-2790-426d-a576-303d1a50a143/bank_accounts/6801013741181/afe7cb45-3114-46e2-a0df-3285fa5dc80d/bank_account/1.8-FNB_62938037018_20230328.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQOIKJL7BXFF7LDWP%2F20230420%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230420T095026Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=2260dda0d0872e0e3d8f73de5f19a52843fc3db69d00dbad551550b22073cf26",
            "expires_in": "60m",
            "file": {
                "id": 27424,
                "name": "1.8 FNB_62938037018_20230328.pdf",
                "type": "pdf",
                "url": "https://apply.fincheck.co.za/fincheck/documents/1.8%20FNB_62938037018_20230328.pdf"
            },
            "month": "Feb 2023",
            "fraud": {
                "fraud_checks": {
                    "create_date": false,
                    "meta_mod_date": false,
                    "meta_producer": false,
                    "meta_creator": false,
                    "meta_author": false
                }
            },
            "processed": false
        },
        {
            "id": "{{$randomUUID}}",
            "bank_account_id": "{{bankAccountId}}",
            "statement_date": "2023-02-28",
            "start_date": "2023-01-28",
            "end_date": "2023-02-28",
            "temp_url": "https://fincheck-onboarding.s3.eu-west-1.amazonaws.com/production/client_e5354855-2790-426d-a576-303d1a50a143/bank_accounts/6801013741181/afe7cb45-3114-46e2-a0df-3285fa5dc80d/bank_account/1.7-FNB_PREMIER_CURRENT_ACCOUNT_12.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQOIKJL7BXFF7LDWP%2F20230420%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230420T095026Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=901cae7a7e8b856c9f45e29e6e15a7635eea68a1c01f3cc7486631d8869fe05d",
            "expires_in": "60m",
            "file": {
                "id": 27425,
                "name": "1.7 FNB_PREMIER_CURRENT_ACCOUNT_12.pdf",
                "type": "pdf",
                "url": "https://apply.fincheck.co.za/fincheck/documents/1.7%20FNB_PREMIER_CURRENT_ACCOUNT_12.pdf"
            },
            "month": "Jan 2023",
            "fraud": {
                "fraud_checks": {
                    "create_date": false,
                    "meta_mod_date": false,
                    "meta_producer": false,
                    "meta_creator": false,
                    "meta_author": false
                }
            },
            "processed": false
        }
    ]
}

Webhook Requirements | statement_result_url

The webhook gets triggered once the processing of the transactions in the statement(s) is successful. Once you receive this successful payload, you can query any of the /transactions, /statements, /accounts and /transaction-reports endpoints to retrieve the affordability data you require.

As this is a specific post query, we need to make sure we are sending customer/clients to a safe destination, as such, there is validation done on the Redirect and Statement Result URL.

The Filed under validation must have a valid A or AAAA record when querying the dns_get_record PHP function.

A a simple guideline:

• Must be RFC compliant

• Must include the hostname

• Be careful with special characters that might mess with the structure of the post request

Statement Upload V1.1 – Statement Success

{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": true,
"code": "statement-success",
"tenant": "{{tenantid}}",
"message": "Success”,
"bank_account_id": "{{bankaccountid}}”
}
}

Statement Upload V1.1 – Statement Failure

{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": false,
"code": "statement-failed",
"tenant": "{{tenantid}}",
"message": "Failure”,
"bank_account_id": "{{bankaccountid}}”
}
}