⚡Bank Statement Upload V1.1

The new endpoint for uploading Bank Statements does validation on the upload request and does verification and storing of transactions as a background job once the statement_result_url added.

In Bank Statement Upload V1.1 has moved the transactional processing and storing of statements to become an asynchronous job. This means within the upload call, the validation checks are performed and the transactional processing is completed as a background task. Therefore you are only able to upload a maximum of six statements at a time.

Upload Bankstatement V1.1

POST {{environmentUrl}}/{{tenantId}}/api/v1.1/bank-accounts/:bank_account_id/upload-bankstatement

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

Path Parameters

Key	Type	Description
bankAccountId*	String	The UUID for a Bank Account that gets generated and returned in the POST Create new Bank Account response. It ensures that the transactional data and statements retrieved in the online login session are saved to the correct Bank Account.

Request Body

The bank statement/s MUST be in PDF format!

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.
return_accuracy	Boolean	Set this to true in order to get the accuracy_metrics object for Scanned Statements. The accuracy_metrics object will be returned in the Return All Statements of a BankAccount endpoint.

Status Codes

200 - OK

Multiple Statement Upload Success

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

400 - Bad Request

Invalid Bank

[
    {
        "code": "invalid_bank",
        "message": "There was an error validating the statement",
        "data": {
            "error": "Could not be recognised as a valid FNB statement. Please check if it is a valid bank statement, and that your bank selection is correct."
        }
    }
]

Duplicate Statement

[
    {
        "code": "duplicate_statement",
        "message": "There was an error validating the statement",
        "data": {
            "error": "{\"message\":\"Duplicate statement. Please upload a different statement from the last 3 months.\",\"statement_date\":\"Feb 2023\"}"
        }
    }
]

Upload Limit

[
    {
        "code": "file_upload_limit",
        "message": "There was an error uploading the bank statements",
        "data": {
            "error": "The bank statement upload functionality only caters for the upload of 6 concurrent bank statements."
        }
    }
]

422 - Unprocessable Content

Invalid Layout

[
    {
        "code": "invalid_layout",
        "message": "There was an error validating the statement",
        "data": {
            "error": "Invalid bank statement - layout"
        }
    }
]

Invalid Bank

[
    {
        "code": "invalid_bank",
        "message": "There was an error validating the statement",
        "data": {
            "error": "Could not be recognised as a valid Absa statement. Please check if it is a valid bank statement, and that your bank selection is correct."
        }
    }
]

Invalid Format

[
    {
        "code": "invalid_format",
        "message": "There was an error validating the bank statement.",
        "data": {
            "error": "The bank statement provided is not in an accepted file format. Please upload a PDF bank statement generated from your banking profile."
        }
    }
]

Invalid Password

[
    {
        "code": "invalid_password",
        "message": "There was an error decrypting the bank statement.",
        "data": {
            "error": "The bank statement provided is password protected. Please upload a PDF bank statement that is not password protected."
        }
    }
]

Invalid Period

[
    {
        "code": "invalid_period",
        "message": "There was an error validating the statement",
        "data": {
            "error": "{\"message\":\"The provided statement is too old. Please upload a statement from the last 3 months.\",\"statement_date\":\"Dec 2022\"}"
        }
    }
]

Custom Bank Statement Validations

As part of bank statement upload V1.1, there are optional validations performed upon statement upload.

Account Holder Validation

The account holder validation will perform a comparison between the Customers details captured in POST Create New Customer and the Customers details on the bank statement uploaded.

422 - Unprocessable Entity

[
    {
        "code": "failed_validation",
        "message": "There was an error validating the bank statement",
        "data": {
            "error": "The bank statement account holder does not match customer details. Please check if the correct bank statement, and customer details have been provided."
        }
    }
]

Account Number Validation

The account number validation will perform a comparison between the account number details captured in POST Create New Bank Account and the Customers account number on the bank statement uploaded.

422 - Unprocessable Entity

[
    {
        "code": "failed_validation",
        "message": "There was an error validating the bank statement",
        "data": {
            "error": "The bank statement account number does not match customer details. Please check if the correct bank statement, and customer details have been provided."
        }
    }
]

Webhook Requirements | statement_result_url

The following is the payload that gets sent to the url that is provided in the statement_result_url parameter in the POST Upload Bankstatement v1.1 request.

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}}”
}
}