# Best practices
Statement processing is a convenient way for you to obtain transaction histories via your app. However there are some non-obvious development challenges in making a simple to use statement uploader. Make sure that you address these issues otherwise you might find a big drop-off in usage because your users find it too difficult or inconvenient to upload statements.
This article provides guidelines to developers on what information to expose to your users when integrating the Spike API into your own custom application.
# Client use-cases
How you display errors depends on what type of usage you have for statements:
If you are a lender
- then you will typically have 2 types of app:
- a loan application where applicants can submitting pdfs (usually via a statement uploader)
- and a review tool where credit-clerks can review transactions that have been captured from these statements and approve or deny the loan application
- your goals are:
- you may not want to give applicants an opportunity to correct errors (e.g. alerting them to the fact that you detected that they have modified a statement) but you do want to point out other errors that they can correct (like for example that their password is incorrect)
- you want to show all error and warnings to credit-clerks - e.g. they should be alerted when modifications are detected, and they need to know when to initiate a support query with Spike
If you are a personal financial manager (PFM):
- then you will typically have 2 use-cases:
- a budgeting tool where your users can upload pdfs for budgetary analysis
- a help desk who might assist users in resolving statement processing issues
- your goals are:
- to surface all statement processing errors so that users can resolve any errors that are within their power to resolve - e.g. supply the correct password, or submit the original if they uploaded a modified statement
- allow helpdeskers to determine the cause of the error so that they can guide users in how to resolve the problem
# Background info
- browser generated statements[1]
- print to pdf statements
- modified statements
# User resolvable errors
Some errors are fixable by the user or applicant who submitted the pdf:
| cause | resolution |
|---|---|
| bad password | fix password |
| bad pdf | send valid pdf |
| unsupported pdf | send supported pdf |
| modified | send original |
# Errors
| Error Code | cause | can be caused by modification? | contact | user resolvable |
|---|---|---|---|---|
| can't process pdf | ||||
| pdf/fail/password-required | password | fix password | ||
| pdf/fail/password-incorrect | password | fix password | ||
| pdf/fail/invalid-pdf | bad pdf | ✔️ | send valid pdf | |
| pdf/fail/extract-failed | bad pdf | ✔️ | send valid pdf | |
| unsupported pdf | ||||
| pdf/fail/auto-detect | unsupported | send supported pdf | ||
| pdf/fail/image-pdf | unsupported | send supported pdf | ||
| identification failed | ||||
| pdf/fail/unknown-pdf | unsupported, new, mod | ✔️ | if not modified | if modified? send original |
| pdf/fail/multiple-matching-parsers | spike error | ✔️ | if not modified | if modified? send original |
| parse failed | ||||
| pdf/fail/failed-to-extract-statement-date | spike error | ✔️ | if not modified | if modified? send original |
| pdf/fail/failed-to-extract-credit-breakdown | spike error | ✔️ | if not modified | if modified? send original |
| pdf/fail/invalid-data-extracted | partial extract | ✔️ | if not modified | if modified? send original |
| internal | ||||
| pdf/fail/unknown-exception | spike error | ✔️ | if not modified | if modified? send original |
| error/common/exception | spike error | ✔️ | if not modified | if modified? send original |
| other | ||||
| error/common/dev/authorization | client error | |||
| error/common/access/insufficient-credit | client error | |||
| error/common/dev/invalid-inputs | client error |
# Best-practices for lenders
# Statement uploader for applicants
- password checks
- when you receive a pdf from a user first check to see whether it is password protected and also check that the supplied password works, before sending the pdf to the Spike API
- errors
- see resolvable by the user
- only show resolution advice for:
password,bad pdf, andunsupportederrors
- do NOT show any advice if the pdf has been
modified- you don't want to alert scammers to the fact that their modifications have been detected
Other advice
- retain
spike requestIdfor each request with a mapping toyour userId[2]
# Application review tool for credit-clerk
- success but modified
- alert your credit-clerks to the fact that we detected that the statement has been modified
- this modification may not be fraudulent or malicious, but the credit-clerk should apply additional scrutiny to the application
- errors
- show full error code with a link (to https://docs.spikedata.co.za/product/support/errors/codes/...) as well as an indication of whether the statement has been modified
- so that the credit-clerk can initiate a support request
- NOTE: they should NOT raise a support request if:
- the statement is resolvable by the user
- see the errors table
- NOTE: they should NOT raise a support request if:
Other advice
- link to
spike requestIdin case support request must be raised[2:1]
# Best-practices for budgeting tools
# Statement uploader for users
- password checks
- when you receive a pdf from a user first check to see whether it is password protected and also check that the supplied password works, before sending the pdf to the Spike API
- show resolution advice where the error is resolvable by the user
- for many error codes this will require checking whether the statement has been modified or not (see
user resolvablecolumn in the errors table)
- for many error codes this will require checking whether the statement has been modified or not (see
Other advice
- optionally show full error code with link to https://docs.spikedata.co.za/product/support/errors/codes/...
- retain
spike requestIdfor each request with a mapping toyour userId[2:2]
# Support tools for helpdeskers
- user sends support request with a pdf
- help deskers upload pdf on spike web converter
- user doesn't send support request
- error digest = daily email of errors
- error dashboard = show failed pdfs with
contactoruser resolvable
# Summary
How do I make my uploader simple for my users to use?
- follow the web app sample (opens new window)
- the sample provides working examples of dealing with:
- handling non-pdf files
- handling password protected pdfs
- allowing upload of multiple pdfs
How should I make use of modification detection?
- do not show to loan applicants
- do show to PFM users
- do show to credit clerks
there is a higher error rate with browser-generated statements, however these are not fake statements ↩︎
the requestId is used by spike to uniquely identify the request: (1) it is used on many screens (e.g. the history screen) in the Spike app and (2) it can be used for support queries. Its useful to map the spike request to the user on your app that initiated the request. It may also be possible to forge this link by bank account number - provided that this is extract successfully by spike (usually not the case with errors). ↩︎ ↩︎ ↩︎
← pdf Quick start→