Lines of Credit (alpha)

A Line of Credit (LoC) account is used to offer credit to customers of a fintech. It allows a borrower to utilize funds, as needed, up to a predetermined limit. The borrower may then repay the funds and borrow again as needed.

Application

In order to create a Line of Credit account, Fintechs and their customers need to setup and create a credit application. A credit application consists of an application status and application details. This allows the fintech to offer credit to their customer and record whether the extended credit offer has been accepted or denied by the customer.

After creating an application, the fintech or its customers can then proceed to use an account template to create an account. You can use the Accounts API to create and manage accounts.

Integration steps

The curl examples assume you have set up baseurl and apikey environment variables. See Base URL and Authentication for instructions. Some examples depend on identifiers generated by previous steps. These are indicated like {APPLICATION_ID}.

  1. Add Credit Funding into the Funding Account with either Internal Transfer via Internal Transfer API spec or ACH into the Funding Account

  2. Create an Account Template of Type LINE_OF_CREDIT with Account Template API Spec:

    New Attributes added to Account Templates are:

    • Minimum Payment, this must be set either on the account template level or at the account level for LoC.
      • Rate is in BPS (i.e. 125 = 1.25%)
      • Amount is in cents (i.e. $25 = 2500)
      • Type is only allowed to be AMOUNT_OR_PERCENTAGE for now.
    • Grace Period is the number of days past the end of month billing date of when the payment is due (i.e. grace period days = due date - preceeding billing date)
     curl -X POST \
         -H 'Authorization: Bearer $apikey' \
         -H 'Content-Type: application/json' \
         -d '
         {
             "name": "Line of Credit Template",
             "description": "An account template for Line of Credit accounts",
             "is_enabled": true,
             "template": {
                 "account_type": "LINE_OF_CREDIT",
                 "currency": "USD",
                 "bank_country": "US",
                 "minimum_payment": {
                     "type": "AMOUNT_OR_PERCENTAGE",
                     "amount": 2500,
                     "rate": 125
                 },
                 "grace_period": 25,
             }
         }' $baseurl/v0/accounts/templates
    
  3. Create a Person via Person API spec

  4. Have the Person pass KYC Verification using: KYC Verification API Overview

  5. Create an Application - POST /v0/applications

    curl -X POST \
        -H 'Authorization: Bearer $apikey' \
        -H 'Content-Type: application/json' \
        -d '
        {
            "customer_id": "{CUSTOMER_UUID}",
            "status": "APPLICATION_SUBMITTED",
            "type": "LINE_OF_CREDIT",
            "application_details": {
                "fico_score": 700,
                "annual_salary": 50000
            }
        }' $baseurl/v0/applications
    

    Sample response body:

    {
      "id": "{APPLICATION_UUID}",
      "customer_id": "{CUSTOMER_UUID}",
      "status": "APPLICATION_SUBMITTED",
      "type": "LINE_OF_CREDIT",
      "application_details": {
        "fico_score": 700,
        "annual_salary": 50000
      },
      "creation_time": "2022-04-12T14:15:22Z",
      "last_updated_time": "2022-04-12T14:15:22Z"
    }
    
  6. Offer the person a credit of 1000

  7. Update the application - PATCH /v0/applications/{APPLICATION_UUID}

    curl -X PATCH \
        -H 'Authorization: Bearer $apikey' \
        -H 'Content-Type: application/json' \
        -d '
        {
            "status": "CREDIT_APPROVED"
        }' $baseurl/v0/applications/{APPLICATION_UUID}
    

    Sample response body:

    {
      "id": "{APPLICATION_UUID}",
      "customer_id": "{CUSTOMER_UUID}",
      "status": "CREDIT_APPROVED",
      "type": "LINE_OF_CREDIT",
      "application_details": {
        "fico_score": 700,
        "annual_salary": 50000
      },
      "creation_time": "2022-04-12T14:15:22Z",
      "last_updated_time": "2022-04-12T15:15:22Z"
    }
    
  8. Optionally, can also update the application details if the customer has improved their credit or increased his/her fico score - PATCH /v0/applications/{APPLICATION_UUID}

    curl -X PATCH \
        -H 'Authorization: Bearer $apikey' \
        -H 'Content-Type: application/json' \
        -d '
        {
            "application_details": {
                "fico_score": 900,
                "annual_salary": 70000
            }
        }' $baseurl/v0/applications/{APPLICATION_UUID}
    

    Sample response body:

    {
      "id": "{APPLICATION_UUID}",
      "customer_id": "{CUSTOMER_UUID}",
      "status": "CREDIT_APPROVED",
      "type": "LINE_OF_CREDIT",
      "application_details": {
        "fico_score": 900,
        "annual_salary": 70000
      },
      "creation_time": "2022-04-12T14:15:22Z",
      "last_updated_time": "2022-04-12T16:15:22Z"
    }
    
  9. Customer accepts the credit offered

  10. Update the application - PATCH /v0/applications/{APPLICATION_UUID}

    curl -X PATCH \
        -H 'Authorization: Bearer $apikey' \
        -H 'Content-Type: application/json' \
        -d '
        {
            "status": "CREDIT_ACCEPTED"
        }' $baseurl/v0/applications/{APPLICATION_UUID}
    

    Sample response body:

    {
      "id": "{APPLICATION_UUID}",
      "customer_id": "{CUSTOMER_UUID}",
      "status": "CREDIT_ACCEPTED",
      "type": "LINE_OF_CREDIT",
      "application_details": {
        "fico_score": 700,
        "annual_salary": 50000
      },
      "creation_time": "2022-04-12T14:15:22Z",
      "last_updated_time": "2022-04-12T17:15:22Z"
    }
    
  11. Create an account of type LINE_OF_CREDIT Accounts API or refer to the Accounts Guide

    curl -X POST \
        -H 'Authorization: Bearer $apikey' \
        -H 'Content-Type: application/json' \
        -d '
        {
            "account_template_id": "{ACCOUNT_TEMPLATE_UUID}",
            "account_purpose": "LOC Account",
            "credit_limit": 1000,
            "application_id": "{APPLICATION_UUID}",
            "relationships": [
                {
                    "relationship_type": "ACCOUNT_HOLDER",
                    "customer_id": "{CUSTOMER_UUID}"
                }
            ]
        }' $baseurl/v0/accounts
    

    Sample response body:

    {
      "access_status": "ACTIVE",
      "account_number": "790586668526",
      "account_purpose": "LOC Account",
      "account_type": "LINE_OF_CREDIT",
      "balance_ceiling": {
        "balance": 1000
      },
      "balance_floor": {
        "balance": 0
      },
      "balances": [
        {
          "balance": 20000,
          "type": "ACCOUNT_BALANCE"
        },
        {
          "balance": 30000,
          "type": "AVAILABLE_BALANCE"
        }
      ],
      "bank_routing": "112233445",
      "creation_time": "2022-04-07T20:37:46.356692Z",
      "currency": "USD",
      "customer_ids": ["{CUSTOMER_UUID}"],
      "customer_type": "PERSONAL",
      "id": "3389aeac-0163-4479-8702-ff8572d39fe8",
      "is_account_pool": false,
      "last_updated_time": "2022-04-07T20:37:46.356692Z",
      "overdraft_limit": 0,
      "status": "RESTRICTED",
      "is_ach_enabled": true,
      "is_card_enabled": false,
      "is_p2p_enabled": true,
      "minimum_payment": {
        "type": "AMOUNT_OR_PERCENTAGE",
        "amount": 2500,
        "rate": 125
      },
      "application_id": "{APPLICATION_UUID}",
      "metadata": {},
      "grace_period": 21
    }
    

Application Status Flow:

The following diagram illustrates all the states the application could be in. Upon creation of the credit application, the status is APPLICATION_SUBMITTED and can flow to other states as seen in the following diagram.
Once the application is in CREDIT_ACCEPTED, a credit account is now allowed to be created.

%%{init: {"fontFamily": "sans-serif"}}%%
stateDiagram-v2
    APPLICATION_SUBMITTED --> CREDIT_APPROVED
    APPLICATION_SUBMITTED --> CREDIT_DENIED
    CREDIT_APPROVED --> CREDIT_ACCEPTED_BY_CUSTOMER
    CREDIT_APPROVED --> CREDIT_NOT_ACCEPTED_BY_CUSTOMER