Digital lending overview

How digital lending works on the Pismo platform.

The Pismo platform enables you to create and manage loans for your customers. You can create loans based on customizable templates called loan products that define disbursement and repayment options. You can also simulate loans, accept repayments, and settle loans using the Pismo Lending API.

For more information, see the Lending API reference.

📘

The Pismo platform helps manage the creation, disbursement and repayment of loans, but does not originate loans directly. Contact your Pismo representative about arranging any required digital lending partnerships.

Loan products

A loan product is a template containing a set of configurations inherited by the new loans you create based on it. You can create as many loan products as you need to reflect the kinds of loans you want to offer your customers. For example, you might create one BNPL loan product for a set of similar merchandise in your storefront, or you might create many loan products, one for each individual product you sell.

Loan product types

The Pismo platform supports the following types of loan products.

TypeDescriptionFeatures
PersonalA personal loan is an unsecured loan issued to an individual. Personal loans are often in large amounts and repaid over many installments.

Call the Create a loan product endpoint and set product_type to “personal” to create a loan product designed for personal loans.
Installments calculated based on a reducing balance basis.
Weekly, biweekly, monthly, or quarterly installment plans.
Auto-collection of funds from a bank account or card on file.
Partial repayment options with the flexibility to reduce the term of the loan or the installment amount.
Early full loan repayment options to settle the loan account.
Buy Now Pay Later (BNPL)A BNPL loan is an unsecured loan issued at checkout in the amount of the purchase price.

Call the Create a loan product endpoint and set product_type to “BNPL” to create a loan product designed for BNPL loans.
Interest-free periods.
Biweekly or monthly repayment frequencies.
Disbursements directly to merchants.
Auto repayment from a bank account or card on file.
Canceling contracts in case of product returns.
Charges for missed payments or interest after the interest-free period.
Live data streams for notifications, reporting, and integration with Artificial Intelligence/Machine Learning (AI/ML) solutions for collections and risk management.

Disbursement options

The loan product enables you to define the disbursement method of a loan, which defines in how many payments the disbursement is made. You can disburse in one lump sum using the SINGLE option, or over multiple payments using the MULTIPLE option.

Repayment options

Loan products include several attributes that define how a loan's repayment schedule is structured.

Repayment calculation method

You can calculate the repayments to be flat, where the customer pays the same amount each cycle, or reducing, where the customer pays a larger amount in the first cycle and a decreasing amount for each cycle after that.

  • To use the reducing calculation, set the repayment_calculation_method parameter to EI_REDUCING_BALANCE in the Create a loan product endpoint.
  • To use the flat calculation, set the repayment_calculation_method parameter to FLAT_BASIS.

Repayment frequency

You can configure a loan on the Pismo platform to be repaid at the following frequencies:

  • Monthly
  • Yearly
  • Quarterly
  • Fortnightly (Bi-weekly)

Interest rate options

You can amortize the moratorium interest during the remaining term of the loan. To do this, set the moratorium_interest_rate parameter in the Create a loan product endpoint.

You can configure interest-only installments at a specific interest rate. They can help the borrower make smaller payments for a while on the loan. To do this, set the repayment_mode parameter to INTEREST_ONLY in the Create a loan product endpoint.

You can configure the loan so that the borrower can repay it in one payment. To do this, use the early_final_settlement parameter in the Create a loan product endpoint.

Stages

A loan’s repayment schedule can be split into multiple spans of time called stages. For each stage, you can define the following:

  • Repayment mode: Whether repayment includes principal and interest, includes only interest, or is in moratorium (no repayment); defined in the loan product.
  • Interest rate: The rate of interest accrued during this stage; defined in the loan simulation and booking request.
  • Period: The number of payment periods to which this stage applies; defined in the loan simulation and booking request.

For example, to define a stage that lasts three months and charges 5% interest annually each month, you would include the following as part of your POST request to the Simulate a loan booking using a loan product endpoint:

"stages": [  
  {  
   "interest_rate": {  
    "value": 0.05,  
    "unit": "YEAR"  
   },  
   "period": {  
    "value": 3,  
    "unit": "MONTH"  
  }  
 }  
]

📘

Each stage occurs in the order it is listed in the stages array.

When you simulate a loan to generate the repayment schedule, the response includes the details of your stages, and appears as you defined it in the request.

For more information about stages, see Create a loan product and Simulate a loan booking using a loan product.

Rules

A loan product enables you to define limits for the following values at loan creation time using the rules object:

  • Loan amount: The total amount of the loan.
  • Number of installments: The total number of installments the repayment can be split into.
  • Loan term length: The span of time over which repayments can be made.
  • Interest rate: The total interest rate applied to the loan amount.

Charge plan codes

You can use the Pismo platform to add charge plan codes. A charge plan code links service charges or taxes to a product or service. For example, you can apply charge plans to BNPL loans.

To use charge plan codes, add a value to the charge_plan_codes array in your loan product.

The lending lifecycle

This sequence shows how you can create a digital lending experience for your borrowers on the Pismo lending product.

Create the loan product.
❷ When a borrower asks for a loan, create a simulation to show the terms of the loan. The loan simulation creates a payment schedule.
❸ After the borrower accepts the terms of the loan, you book the loan. Booking the loan confirms the payment schedule, validates the rules you defined in the loan product, and creates an ID for the loan.
❹ After you book the loan, you disburse the loan.
❺ When your borrower makes a payment, you register the payment.
❻ After your borrower has made all payments, the Pismo platform auto-settles the loan.

The following diagram illustrates how the Pismo platform manages the life of a loan.

**Pismo loan management lifecycle****Pismo loan management lifecycle**

Pismo loan management lifecycle

StageDescription
SimulateSimulates loan repayments or equated monthly installment (EMI) amounts.
BookBooks the loans as soon as it’s approved by the underwriters.
DisburseCredits into the customer’s account (within or outside the bank), collects charges, or disburses as a single amount or multiple amounts.
RepayAuto-repays a loan through standing instructions.
SettleAuto-settles the loan amount upon full repayment or carries the restructure in case of hardship.

Create the loan product

To create a loan, you must have a loan product. Use the Create a loan product endpoint to get started.

Simulate the loan

Use the Simulate a loan booking endpoint to show a potential borrower the loan terms, such as the interest rate and repayment schedule. If the borrower accepts the terms, the Pismo platform generates the official repayment schedule and loan terms when you book the loan.

This API request example includes these fields.

FieldDescription
product_idThe ID of a loan product.
loan_amountThe total amount of the loan.
start_dateThe starting date of the loan.
stagesThe loan interval details, such as interest rate and how often repayments occur.
disbursement.due_dateThe date when to disburse the loan.
{
  "product_id": "8753ee7e-d227-4bcf-bd10-af03afca738e",
  "loan_amount": 1000.00,
  "start_date": "2022-06-24",
  "stages": [
    {
        "interest_rate":{
            "value": 0.12,
            "unit": "YEAR"
        },
        "period": {
            "value": 3,
            "unit": "MONTH"
        }
    }
  ],
  "disbursement": [
    {
      "due_date": "2022-06-24"
    }
  ]
}

After you simulate the loan, the API response includes the loan_simulation_id, which you use to identify the simulation when you book the loan. The response also includes the repayment_schedule, which shows the details of the loan schedule, and the disbursement_schedule, which shows the details of the loan disbursement.

{
    "loan_simulation_id": "ae401396-2438-4ff8-8894-27720057522c",
    "product_id": "8753ee7e-d227-4bcf-bd10-af03afca738e",
    "loan_amount": 1000.00,
    "outstanding_balance": {
        "principal": 1000.00,
        "interest": 20.07,
        "total": 1020.07
    },
    "total_payment_amount": 1020.07,
    "start_date": "2022-06-24",
    "days_in_year_method": "ACTUAL_ACTUAL",
    "repayment_calculation_method": "EI_REDUCING_BALANCE",
    "repayment_frequency": {
        "unit": "MONTH"
    },
    "repayment_schedule": [
        {
            "period": 1,
            "payment_amount": 340.02,
            "due_date": "2022-07-24",
            "principal_amount": 330.02,
            "interest_amount": 10.00,
            "fee_amount": 0.00,
            "balance": 669.98,
            "number_of_days": 30,
            "auto": false
        },
        {
            "period": 2,
            "payment_amount": 340.02,
            "due_date": "2022-08-24",
            "principal_amount": 333.32,
            "interest_amount": 6.70,
            "fee_amount": 0.00,
            "balance": 336.66,
            "number_of_days": 31,
            "auto": false
        },
        {
            "period": 3,
            "payment_amount": 340.03,
            "due_date": "2022-09-24",
            "principal_amount": 336.66,
            "interest_amount": 3.37,
            "fee_amount": 0.00,
            "balance": 0.00,
            "number_of_days": 31,
            "auto": false
        }
    ],
    "disbursement_schedule": [
        {
            "date": "2022-06-24",
            "amount": 1000.00,
            "principal": 1000.00,
            "tax": 0.00,
            "fee": 0.00,
            "charge": 0.00
        }
    ],
    "stages": [
        {
            "interest_rate": {
                "value": 0.12,
                "unit": "YEAR"
            },
            "period": {
                "value": 3,
                "unit": "MONTH"
            }
        }
    ]
}

📘

To find an existing loan simulation, use the Retrieve a loan simulation by ID endpoint. This is useful if there’s a delay in booking a loan with the borrower.

Book the loan

After the borrower accepts the terms of the loan from the simulation, use the Create a loan booking endpoint. When you book the loan, you confirm the payment schedule from the loan simulation.

This API request example includes these required fields.

FieldDescription
loan_simulation_idThe ID of the simulated loan with the payment schedule.
account_idThe ID for the account registered on the Pismo platform.
{
 "loan_simulation_id": "ae401396-2438-4ff8-8894-27720057522c",
 "external_id": "LOAN_TRACKER_1",
 "account_id": 103614168
}

After you book the loan, the API response shows the loan_id. The loan_id is the identifier for the entire life of the loan. So, if you need to check or edit any details of the loan, use its loan ID.

{
   "loan_id": "5d9d9339-3b5e-4c33-b129-8155e4d4946b"
}

Disburse the loan

After the borrower agrees to book the loan, use the Disburse a loan endpoint.

The current disbursement status is stored in the loan object as disbursement_schedule. The status can be SCHEDULED or DONE. It also includes the date of the scheduled or actual disbursement.
Use the Retrieve Loan Details by ID endpoint to view information about a loan’s disbursement.

Depending on your lending rules, you can perform instant disbursement into a customer’s account, or, in the case of BNPL, a merchant’s account. Instant disbursement means the loan life cycle can begin much quicker. If your organization allows, you can disburse funds on the same day using the disbursement_date parameter.

You also have the flexibility to disburse funds to an account registered on the Pismo platform or to an external account.

  • To disburse funds to an account registered on the Pismo platform, use the INTERNALDISBURSETO parameter in the Disburse a loan endpoint.
  • To disburse funds to an external account, use the EXTERNALDISBURSETO parameter in the Disburse a loan endpoint.

You can also deduct fees or charges from the disbursement amount. To do this, use the disbursement_schedule parameter when you simulate the loan.

This API request example includes these required fields.

FieldDescription
disbursement_dateThe date to disburse the loan. You can find this date in the loan simulation.
disbursement_amountThe amount disbursed for the loan. You can find this amount in the loan simulation.
disbursement_accountThe account on the Pismo platform to which the loan funds are disbursed.
{
 "disbursement_date": "2022-06-24",
 "disbursed_amount": 1000.00,
 "disbursement_account": {
   "type": "INTERNAL",
   "account_id": 103614168
 }
}

After you disburse the loan, the API response includes the disbursement_id. This ID is the identifier that confirms the loan disbursement.

{
   "loan_id": "5d9d9339-3b5e-4c33-b129-8155e4d4946b",
   "disbursement_id": "c1eb9f28-e1c9-4705-b2b5-f986b3bc7455",
   "created_at": "2022-06-27T14:19:30.194249",
   "updated_at": "2022-06-27T14:21:00.318043",
   "product_id": "fb525f7e-4317-45da-84d5-ccb1b0da3f14",
   "disbursement_status": "PROCESSING",
   "loan_amount": 1000.00,
   "disbursed_amount": 1000.00,
   "disbursement_account": {
       "type": "INTERNAL",
       "account_id": 103296044
   }
}

Register the repayment

Now that the loan is active, the borrower needs to repay the loan.

To accept a repayment from a borrower, use the Register a repayment endpoint. To retrieve repayment details for an existing loan, use the Retrieve Loan Details by IDendpoint. Both endpoints require a loan ID in the path parameter, which defines the loan being repaid or retrieved, respectively.

The API request example includes these required fields.

FieldDescription
repayment_idThe unique identifier for the repayment.
repayment_dateThe date the borrower made the repayment.
repayment_amountThe amount of the repayment.
{
 "repayment_id": "1f98f3b1-7492-4846-9787-bf2c1713ab53",
 "repayment_date": "2022-07-12",
 "repayment_amount": 200.00,
 "external_id": "c36e7f4e-db9f-423b-bb42-b6c042c21129"
}

After you process the repayment, the API response shows the loan_id and repayment_id. This confirms you registered the payment.

{
   "loan_id": "5d9d9339-3b5e-4c33-b129-8155e4d4946b",
   "repayment_id": "1f98f3b1-7492-4846-9787-bf2c1713ab53,"
   "repayment_amount": 200,
   "external_id": "c36e7f4e-db9f-423b-bb42-b6c042c21129"
 
}

In a happy path scenario, the borrower continues to repay the installments on time until the loan is repaid in full.

Auto-settlement

After the borrower repays the loan in full, the Pismo platform automatically closes the loan and sends the loan_status_change_1 event.

{
   "loan_id": "6e22999f-8ef9-419c-be38-cac58f923dc7",
   "external_id": "17f8103e-1719-484f-bbfa-10f0fff4edaa",
   "previous_loan_status " : "ACTIVE",
   "current_loan_status ": "SETTLED",
   "created_at": "2022-06-27T01:44:20",
   "product_id": "ca558936-bea1-4ff5-9bbe-21d6bd7eb8e1",
   "account_id": 103295925,
   "loan_amount": 1000.00,
   "outstanding_balance": {
       "principal": 1000.00,
       "interest": 20.07,
       "total": 1020.07
   },
   "total_payment_amount": 1020.07,
   "start_date": "2022-06-27"
}

Use this event to notify borrowers that their loan repayments are complete and the loan is settled.


Related pages