Digital lending overview

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.

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.

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.

{
  "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.

{
 "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.

{
 "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.

{
 "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.