Upload Bankstatement for a Customer v1.1 (Bank Identification Service)
Our Bank Identification Service allows you to upload bank statements without creating a BankAccount first. Gathr will automatically identify the bank from the statement template.
How it Works
Upload Process: When using the Upload BankStatement for Customer v1.1 endpoint, the customer uploads one or more statements without needing to create a BankAccount.
Bank Identification: Gathr identifies the bank using elements such as the bank registration number, bank stamps, QR codes (like those on Capitec statements), logos, and the placement of certain account information on the statement.
BankAccount Creation: Once the bank is identified, a BankAccount of type 'statement' is created for that bank.
Endpoint
Upload Bankstatement for Customer V1.1
POST {{environmentUrl}}/{{tenantId}}/api/v1.1/customers/{{customerId}}/upload-bankstatement
Maximum Statements: Up to 6 bank statements can be uploaded in one API call.
Query Parameters
Key
Value
Description
statements[]*
form-data
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 webhook results of the 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
Upload Response
The successful response for this endpoint contains the following information:
bankAccountId
Statement dates
temp_url where the bank statement is stored
File information including the file name
Month that the statement is for
Fraud checks (excluding the statement_balance fraud check which can be found on the Return All Statements of a BankAccount endpoint once the statement has been processed)
You will receive the BankAccountId in the Upload Bankstatement for Customer v.1.1 endpoint. You will need to store this BankAccountId should you wish to upload additional bank statements to the same BankAccount in future. You would use the Upload Bankstatement v1.1 endpoint to upload these additional statements. The statements would then need to be from the same bank.
This occurs if there is already a bank statement on the Customer with the same information.
[
{
"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\"}"
}
}
]
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 format. Please upload a valid PDF bank statement."
}
}
]
Invalid Layout
[
{
"code": "invalid_layout",
"message": "There was an error validating the statement",
"data": {
"error": "Invalid bank statement - layout"
}
}
]
Invalid Bank
This occurs if the bank has been identified, however the rest of the statement does not match an existing template in our library.
[
{
"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."
}
}
]
Failed Account Holder Validation
[
{
"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."
}
}
]
Failed Account Number Validation
[
{
"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."
}
}
]
Invalid Password (unable to decrypt with Customer's ID Number)
[
{
"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 (too old)
[
{
"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\"}"
}
}
]
File Upload Limit (exceeds maximum of 6 allowed)
[
{
"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."
}
}
]
Duplicate Statements
If there is an existing record of the same bank statement having been uploaded to a given Customer, you will get a duplicate error. You can not upload more than one instance of a certain statement to the same Customer.
How do I know when processing is complete?
Once processing is complete, you will receive astatement-success message to the webhook address you provided as the statement_result_url in the query parameters of the Upload Bankstatement for Customer v1.1 endpoint.
After receiving the statements-success webhook, you can query the /transactions, /statements, /accounts, and /transaction-reports endpoints to retrieve the affordability data you require.
Webhook Requirements
Webhook URL: The statements-success webhook will be sent to the statement_result_url provided in the Upload Bankstatement for Customer endpoint once the statement is processed.
Validation: Ensure the redirect and statement result URL are validated. The URL must have a valid A or AAAA record when querying the dns_get_record PHP function.
Guidelines:
Must be RFC compliant
Must include the hostname
Avoid special characters that might disrupt the post request structure
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. on the types of statements that can be uploaded.
