🚮Return All Failed Statements

Return all the failed PDF files and reasons for a Bank Account Record.

This API call is useful if a manual review process is required within the application journey.

Example: A Customer uploads a Proof of Income document within their application process, instead of a valid PDF Bank Statement, an agent will be able to view the failed document submitted, contact the Customer and support the Customer with the collection of the correct documents.

We have seen in the past that Customers don't always upload the expected bank statement. They possibly upload a statement from a different bank (i.e. they say they're uploading an FNB statement and proceed to upload a Capitec statement), or they upload a scan of their bank statement rather than the original bank statement downloaded directly from their Banking Profile, or perhaps even a random PDF document, such as a payslip or tax invoice.

When the Customers attempts to upload the above scenarios through Upload Bankstatement V1.0 or Upload Bankstatement V1.1, the upload will fail due to the variety of upfront document validations our service performs.

We have catered for a failed PDF document retrieval process where failed files are stored within the Return All Failed Statements of a BankAccount endpoint.

See below in the flow diagram how the service works.

How long do we store the files?

We have a purging policy of 7 days for all failed PDF files. After the 7 days, the failed PDF files will be deleted and unavailable for collection.

In addition to the document purging policy, the "temp_url" is valid for 60 minutes after the endpoint is called to action.

When do we store the files and when don't we store the files?

error_code	error description	Example
duplicate_statement	Duplicate statement. Please upload a different statement from the last 3 months.	The Customer uploads the same statement that they have already uploaded to the BankAccount. E.g. They upload their January bank statement twice. The statement could be valid or invalid. We will throw the duplicate_statement error if the same file is uploaded to the same BankAccount twice.
invalid_bank	Could not be recognised as a valid capitec statement. Please check if it is a valid bank statement, and that your bank selection is correct	The Customer uploads a valid PDF Bank Statement for a bank other than the bank that the BankAccount was created for. E.g. The BankAccount created was for Capitec, but the Customer uploaded an FNB statement.
invalid_layout	Invalid bank statement - layout	The Customer uploads a completely arbitrary PDF document that cannot be identified as a Bank Statement for any bank. E.g. The Customer uploads a PDF of their Municipal Bill.
invalid_period	The provided statement is too old. Please upload a statement from the last 3 months.	The Customer uploads a Bank Statement that is too old.
invalid_scanned	The bank statement provided is not in an accepted file format format. Please upload a PDF bank statement generated from your banking profile	The Customer Uploads a scan of their Bank Statement instead of the original that has been downloaded from their Online Banking.
*unknown_error		Most documents will fail one of the validations before reaching this point. However, there are rare occasions where you might see this error. In general it is an uncaught error and you will have seen a 500 Internal Server Error on the Upload response. We cannot guarantee that the file will be returned for ALL* instances of this error.

error_code

error description

Example

duplicate_statement

Duplicate statement. Please upload a different statement from the last 3 months.

The Customer uploads the same statement that they have already uploaded to the BankAccount. E.g. They upload their January bank statement twice. The statement could be valid or invalid. We will throw the duplicate_statement error if the same file is uploaded to the same BankAccount twice.

invalid_bank

Could not be recognised as a valid capitec statement. Please check if it is a valid bank statement, and that your bank selection is correct

The Customer uploads a valid PDF Bank Statement for a bank other than the bank that the BankAccount was created for. E.g. The BankAccount created was for Capitec, but the Customer uploaded an FNB statement.

invalid_layout

Invalid bank statement - layout

The Customer uploads a completely arbitrary PDF document that cannot be identified as a Bank Statement for any bank. E.g. The Customer uploads a PDF of their Municipal Bill.

invalid_period

The provided statement is too old. Please upload a statement from the last 3 months.

The Customer uploads a Bank Statement that is too old.

invalid_scanned

The bank statement provided is not in an accepted file format format. Please upload a PDF bank statement generated from your banking profile

The Customer Uploads a scan of their Bank Statement instead of the original that has been downloaded from their Online Banking.

*unknown_error

Most documents will fail one of the validations before reaching this point. However, there are rare occasions where you might see this error. In general it is an uncaught error and you will have seen a 500 Internal Server Error on the Upload response. *We cannot guarantee that the file will be returned for ALL instances of this error.

error_code description Example

error_code	description	Example
invalid_format	The bank statement provided is not in an accepted file format. Please upload a PDF statement.	If the Customer uploads a file that is not of format type PDF. E.g. The Customer uploads a JPEG or PNG file.
validation_failed	The bank statement account holder does not match customer details. Please check if the correct bank statement, and customer details have been provided. The bank statement account number does not match customer details. Please check if the correct bank statement, and customer details have been provided.	The Customer uploads a file where the AccountHolder name read from the statement does not match the details for `first_name` and `last_name` that has been stored on the Customer (i.e. when the Customer was Created). E.g. The Customer uploads a Statement that has `John Doe` as the AccountHolder on it, but the Customer's name is `Anthony Smith` (according to the details they provided on Create New Customer).

invalid_format

The bank statement provided is not in an accepted file format. Please upload a PDF statement.

If the Customer uploads a file that is not of format type PDF. E.g. The Customer uploads a JPEG or PNG file.

validation_failed

The bank statement account holder does not match customer details. Please check if the correct bank statement, and customer details have been provided. The bank statement account number does not match customer details. Please check if the correct bank statement, and customer details have been provided.

The Customer uploads a file where the AccountHolder name read from the statement does not match the details for first_name and last_name that has been stored on the Customer (i.e. when the Customer was Created). E.g. The Customer uploads a Statement that has John Doe as the AccountHolder on it, but the Customer's name is Anthony Smith (according to the details they provided on Create New Customer).

Return All Failed Statements of a BankAccount

`GET` `{{baseUrl}}/bank-accounts/:bank_account_id/failed-statements`

Path Parameters

Name	Type	Description
bank_account_id*	String	The UUID for a Bank Account that gets generated and returned in the POST Create new Bank Account response.

Name

Type

Description

bank_account_id*

String

The UUID for a Bank Account that gets generated and returned in the POST Create new Bank Account response.

Status Codes

{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/...",
            "expires_in": "60m",
            "file": {
                "id": 4451,
                "name": "FNB_ASPIRE_CURRENT_ACCOUNT_62.pdf",
                "type": "pdf",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/FNB_ASPIRE_CURRENT_ACCOUNT_62.pdf"
            },
            "error_code": "invalid_bank",
            "description": "Could not be recognised as a valid capitec statement. Please check if it is a valid bank statement, and that your bank selection is correct."
        }
    ]
}

{
    "errors": {
        "code": "route_not_found",
        "message": "This route does not exist"
    }
}

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/.....",
            "expires_in": "60m",
            "file": {
                "id": 4452,
                "name": "COJ_2022-06-03_553505211 (4).pdf",
                "type": "pdf",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/COJ_2022-06-03_553505211%20%284%29.pdf"
            },
            "error_code": "invalid_layout",
            "description": "Invalid bank statement - layout"
        }
    ]
}
```

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/....",
            "expires_in": "60m",
            "file": {
                "id": 4456,
                "name": "FNB_ASPIRE_CURRENT_ACCOUNT_58 (1).pdf",
                "type": "pdf",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/FNB_ASPIRE_CURRENT_ACCOUNT_58%20%281%29.pdf"
            },
            "error_code": "invalid_period",
            "description": "{\"message\":\"The provided statement is too old. Please upload a statement from the last 3 months.\",\"statement_date\":\"Sep 2023\"}"
        }
    ]
}
```

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/...",
            "expires_in": "60m",
            "file": {
                "id": 4458,
                "name": "FNB_ASPIRE_CURRENT_ACCOUNT_62.pdf",
                "type": "pdf",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/FNB_ASPIRE_CURRENT_ACCOUNT_62.pdf"
            },
            "error_code": "duplicate_statement",
            "description": "{\"message\":\"Duplicate statement. Please upload a different statement from the last 3 months.\",\"statement_date\":\"Jan 2024\"}"
        }
    ]
}
```

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/.......",
            "expires_in": "60m",
            "file": {
                "id": 4456,
                "name": "FNB_367.jpeg",
                "type": "jpeg",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/FNB_367.jpeg"
            },
            "error_code": "unknown_error",
            "description": "Could not process the document uploaded."
        }
    ]
}
```

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountID}}",
            "temp_url": "https://dev.apply.fincheck.co.za/.......",
            "expires_in": "60m",
            "file": {
                "id": 4456,
                "name": "photo.jpeg",
                "type": "jpeg",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/photo.jpeg"
            },
            "error_code": "invalid_format",
            "description": "The bank statement provided is not in an accpeted file format. Please upload a valid PDF bank statement."
        }
    ]
}
```

```json
{
    "data": [
        {
            "bank_account_id": "{{bankAccountId}}",
            "temp_url": "https://dev.apply.fincheck.co.za/....",
            "expires_in": "60m",
            "file": {
                "id": 4456,
                "name": "FNB_scanned.pdf",
                "type": "pdf",
                "url": "https://dev.apply.fincheck.co.za/fincheck/documents/FNB_SCANNED.pdf"
            },
            "error_code": "invalid_scanned",
            "description": "The bank statement provided is not in an accpeted file format. Please upload a valid PDF bank statement generated from your banking profile."
        }
    ]
}
```

If you wanted to view or download the Bank Statements from successful uploads, you would follow the normal process of calling the Return All Statements of a BankAccount endpoint.

Last updated 15 days ago