Digital lending overview

This page explains how to create and manage loans using the Pismo Lending API. You use loan products to define how loans work, simulate loan terms, book the loan, disburse funds, and register repayments. The Pismo platform manages the entire lifecycle, including auto‑settlement.

For more information on the Pismo Lending API, see the Lending API reference.

📘

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

Loan products

A loan product is a template that defines how a loan behaves. Each loan you create inherits its configuration, including repayment frequency, interest calculation method, and limits. You can create multiple loan products to support the types of loans you offer. 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.

Personal

A personal loan is an unsecured loan issued to an individual and repaid over multiple installments.
To create a personal loan product, call the Create loan product endpoint (v1) and set product_type to personal.

Features include:

• Installments calculated using a reducing balance
• Weekly, biweekly, monthly, or quarterly repayment plans
• Auto‑collection from a bank account or card
• Partial repayment options that adjust installment amount or loan term
• Early full repayment options

Buy now, pay later (BNPL)

A BNPL loan is an unsecured loan issued at checkout for a purchase amount.

To create a BNPL product, call the Create loan product beta endpoint and set product_type to BNPL.

Features include:

• Interest‑free periods
• Biweekly or monthly repayment frequencies
• Disbursement directly to merchants
• Auto‑repayment from a bank account or card
• Contract cancellation for returns
• Charges for missed payments or post‑promotion interest
• Live data streams for notifications, reporting, and AI/ML integrations

Disbursement options

A loan product defines how and when loan funds are released. You can disburse in a single lump sum (SINGLE) or through multiple payments (MULTIPLE). Use the disbursement configuration in the loan product to set the method.

Repayment options

Loan products include settings that define how the Pismo platform calculates repayment schedules.

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 loan product endpoint.
• To use the flat calculation, set the repayment_calculation_method parameter to FLAT_BASIS.

Repayment frequency

Supported repayment frequencies include:

• Monthly
• Yearly
• Quarterly
• Biweekly

Interest rate options

You can configure interest behavior by setting parameters in the loan product:

• Moratorium interest: Amortize accrued interest over the remaining loan term using moratorium_interest_rate in the Create loan product beta endpoint.

• Interest-only installments: Allow reduced payments for part of the loan using repayment_mode = INTEREST_ONLY in the Create loan product beta endpoint.

• Early final settlement: Allow a single final repayment using early_final_settlement in the Create loan product beta endpoint.

Stages

A stage is an interval within the repayment schedule with specific rules. You define stages when simulating or booking a loan.

Each stage includes:

• Repayment mode: Whether repayment includes principal and interest, interest only, or a moratorium
• Interest rate: The rate of interest applied during this stage
• Period: How many payment cycles the stage covers

Stages run in the order they appear in the 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 loan booking endpoint:

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

Rules

Use the rules object in the loan product to define limits for:

• 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

Charge plan codes apply service charges or taxes to loan products. Add them using the charge_plan_codes array in your loan product.

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 loan product endpoint to get started.

Simulate the loan

Use the Simulate 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 Get loan simulation 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 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 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 Get loan details 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 loan endpoint.
• To disburse funds to an external account, use the EXTERNALDISBURSETO parameter in the Disburse 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 repayment endpoint. To retrieve repayment details for an existing loan, use the Get loan details endpoint. 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 changed 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.