A loan product is a template that defines the configuration inherited by loans created from it. You can create as many loan products as needed to reflect the types of loans you offer, such as a single Buy Now Pay Later (BNPL) loan product for a group of similar items in your storefront or separate loan products for each individual product you sell.

Loan product types

The Pismo platform supports the following types of loan products.

Rules

Using the rules object, a loan product enables you to define limits for the following values at loan creation time:

• 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.

1. Create the loan product.
2. When a borrower asks for a loan, use Simulate loan booking to create a simulation to show the terms of the loan. The loan simulation creates a payment schedule.
3. After the borrower accepts the terms of the loan, use Create loan booking to 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.
4. After you book the loan, use Disburse loan to disburse the loan.
5. When your borrower makes a payment, use Register repayment to register the repayment.
6. 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

Before you start creating loans, you need to create at least one loan product. Before you can create a loan product, however, you need to create whatever supporting entities you plan to assign to it. These usually include a repayment hierarchy, a charge plan, a penalty plan (v1 APIs), and interest plan (v2 APIs). Use the Create loan product endpoint to get started along with the following information.

Create penalty plan

Your system

Sends a POST to /lending/v1/penalty-plans with the following payload.

In this example:

• The penalty is defined as a percentage rather than a fixed amount.
• A 10.15% penalty is applied.
• The penalty accrues monthly.
• The penalty applies to multiple balance components, including principal, interest, fees, taxes, charges, and existing penalties.
• The plan is uniquely identified by a code, name, and currency code.

Once created, the penalty plan can be associated with a loan product as part of the overall loan configuration flow.

{
     "percentage": {
          "apply_concerning": [
               "[\"PRINCIPAL\",\"INTEREST\", \"FEE\", \"TAX\", \"CHARGE\", \"PENALTY\"]"
          ],
          "value": 10.15,
          "accrual_frequency": "MONTHLY"
     },
     "code": "pp-0001",
     "name": "penalty-plan-ng522",
     "currency": 999
}

Pismo platform

No events emitted.

Create repayment hierarchy

Your system

Sends a POST to /lending/v2/repayment-hierarchies with the following payload.

In this example, the repayment hierarchy is configured so that principal is the only component considered, and it has the highest (and only) priority.

How the request is structured:

• hierarchy
  Defines the ordered list of loan components that repayments are applied to. In this example, the array contains only "PRINCIPAL", meaning that any repayment amount is applied exclusively to the principal balance.
• code
  A unique identifier for the repayment hierarchy. This code is later referenced when creating a loan product to associate the hierarchy with that product.

{  
     "hierarchy": [  
          "PRINCIPAL"  
     ],  
     "code": "xxxxxx"  
}

Create loan product v1

Your system

Sends a POST to /lending/v1/loan-products with the following payload.

This example shows how to create a personal loan product using the Create loan product v1 endpoint. The request defines a fixed‑rate loan with monthly repayments, single disbursement, and principal‑and‑interest installments, calculated on a reducing balance using simple interest. It also configures repayment timing, interest accrual, early settlement, and prepayment rules, creating a reusable loan‑product template that can be used to simulate, book, and disburse loans. The "interest_type" is set to "SIMPLE", which means interest is calculated only on the original principal amount, not on previously accrued or unpaid interest.

{
     "repayment_frequency": {
          "method": "MONTHLY"
     },
     "loan_type": "FIXED_RATE",
     "interest_collection": "REPAYMENT",
     "days_in_year_method": "ACTUAL_ACTUAL",
     "disbursement": {
          "method": "SINGLE"
     },
     "stages": [
          {
               "repayment_mode": {
                    "type": "PRINCIPAL_AND_INTEREST"
               }
          }
     ],
     "repayment_due": "END_OF_PERIOD",
     "early_final_settlement": {
          "lock_in_period": 9
     },
     "prepayment": {
          "lock_in_period": 9
     },
     "product_id": "PRODUCT_0001",
     "product_name": "78489asdd-151a5sd-123asd-dads250",
     "product_type": "PERSONAL",
     "program_id": 29112022,
     "currency": 999,
     "collateral": "SINGLE",
     "repayment_calculation_method": "EI_REDUCING_BALANCE",
     "interest_type": "SIMPLE"
}

Create loan product v2

Your system

Sends a POST to /lending/v2/loan-products with the following payload.

This example shows how to create a BNPL loan product using the Create loan product v2 endpoint, defining an unsecured, non‑disbursed loan with rate‑based repayment calculations and support for prepayment and early settlement, both governed by percentage‑based penalties and a configurable lock‑in period.

{  
  "product_type": "BNPL",  
  "collateral": "NONE",  
  "disbursement_method": {  
    "type": "NONE"  
  },  
  "repayment_calculation_method": "RATES",  
  "early_final_settlement": {  
    "penalty": {  
      "type": "PERCENTAGE"  
    },  
    "lock_in_period": 9  
  },  
  "prepayment": {  
    "penalty": {  
      "type": "PERCENTAGE"  
    },  
    "lock_in_period": 9  
  }  
}

Pismo platform

Generates a loan_product_creation-1 event:

{
	org_id: "89e56522-726a-453e-ba6d-796b03245128",
	product_id: "BNPL_PRODUCT_2022",
	product_name: "Personal loan 2022",
	product_type: "PERSONAL",
	version: "1",
	created_at: "2022-09-22T19:33:34",
	status: "ACTIVE",
	collateral: "NONE",
	loan_type: "FIXED_RATE",
	repayment_calculation_method: "EI_REDUCING_BALANCE",
	repayment_frequency: [
		method: "MONTHLY",
		interest_type: "SIMPLE"
	],
	days_in_year_method: "ACTUAL_ACTUAL",
	disbursement: "SINGLE"
}