Package: scoreapi
Payment Score APIThis project contains source code and supporting files for theOpen Finance AfricaPayment Score API.
The API is available for consumption athttps//api.openfinance.africaand its reference ishere.
Although the current functionality could have been bundled and utilized as a library, the current plan is to examine its application as an API and, over time, expand it to incorporate data sources where a library would not be suitable.How it worksTL;DR: Head over to thesimulatorto see how the scoring works.A credit score usually takes several factors into account. These factors range from previous loan repayment behavior, down to an individuals age.
Banks and credit bureaus (CRBs) already have the ability to aggregate this data and use it to evaluate loans terms for example.
But accessing standardizedexternalpayment data, easily accessible via API is what this project is about.
For now, the code in this repo simply calculates a payment score. And this score can be used as a datapoint among the factors that lenders (or other financial institutions) may use to determine an individuals creditworthiness.
Banks and credit bureaus aren't the only entities that can find this useful. If you're a business that wants to keep track of payment behaviour, this is for you! E.g. if you're a property management company that want's to keep track of rent payment behavior.Input ValuesTo get a score, you'll need the following:Payment terms:This includes a start/end date, the day of the month a payment is expected, and the amount expected. For example, a tenant may have a lease which starts on Jan 1 2024 (start) to Dec 31 2024 (end) and expected payment date of the 5th.Payment history:: This is a list of payments that have been made by the individual getting scored. This includes the date/time that the payment was made as well as the amount.Score FactorsThe following factors influence that value of a score.On-time paymentHow early an on-time payment is made. A payment made 5 days before the expected payment date is considered better than a payment made at the last minute.Late paymentHow late a payment is made after the expected payment date. A payment made 1 day after the expected payment date is considered better than a payment made 5 days after.The payment amount. If there's an overpayment, like if someone wants to make a payment months ahead, that counts positively towards the score. Partial payments count as well.Payment streaks. This means we take into account consecutive on-time payments or late payments.Score ValueThe score includes scored months which are aggregated into an overall score. The overall score can range from0 to 1(with 1 being an excellent score). Monthly scores may be outside of the 0 to 1 range.
The main pieces of information in a score are:Overall scoreIndividually scored monthsLongest on-time payment streakLongest late payment streakPrerequisites for running locallyIn order to test the API locally, you'll use the Serverless Application Model Command Line Interface (SAM CLI) which is an extension of the AWS CLI that adds functionality for building and testing Lambda applications. It uses Docker to run your functions in an Amazon Linux environment that matches Lambda. It can also emulate your application's build environment and API.To use the SAM CLI, you need the following tools.SAM CLI -Install the SAM CLIPython 3 installedDocker -Install Docker community edition## Using SAM CLI to build and test locallyBuild your application with thesam build --use-containercommand.scoreapi$sambuild--use-containerThe SAM CLI installs dependencies defined insrc/requirements.txt, creates a deployment package, and saves it in the.aws-sam/buildfolder.Test a single function by invoking it directly with a test event. An event is a JSON document that represents the input that the function receives from the event source. Test events are included in theeventsfolder in this project.Run functions locally and invoke them with thesam local invokecommand.scoreapi$samlocalinvokeScoreApiFunction--eventevents/event.jsonThe SAM CLI can also emulate the API. Use the command below to run the API locally on port 3001.scoreapi$samlocalstart-api-p3001Fetch, tail, and filter Lambda function logsTo simplify troubleshooting, SAM CLI has a command calledsam logs.sam logslets you fetch logs generated by your deployed Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug.NOTE: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.scoreapi$samlogs-nScoreApiFunction--stack-namescoreapi--tailYou can find more information and examples about filtering Lambda function logs in theSAM CLI Documentation.TestsTests are defined in thetestsfolder in this project. Use PIP to install the test dependencies and run tests.scoreapi$pipinstall-rtests/requirements.txt--user# unit testsscoreapi$python-mpytesttests/unit-vFormattingscoreapi$pipinstallblack
scoreapi$black.ContributingWe welcome contributions both big and small ❤️Any questions or feedback? Create an issueWant to modify code or docs? Ask to get added as a contributor by emailinghello@openfinance.africaor simply fork the repo to create pull requests