The Pismo platform provides capabilities for managing loans throughout their lifecycle. The platform holds the loan ledger, supports disbursements and repayments, and enables in-life processes such as prepayments, restructures, and early settlement.

For an end-to-end journey map, refer to Lending journey in Lending overview.

For participant definitions and responsibilities for offering and managing loans, refer to Key participants in Lending overview.

Step 1: Create your organization (org)

An org is an object that represents your organization on the Pismo platform. Your Pismo support team creates your org. For more information about org creation and all other onboarding tasks, refer to Pismo platform onboarding.

Step 2: Set up your lending configurations

Programs define the types of accounts a customer can open with your Org, such as credit, debit, and lending accounts. You can't create customer accounts without at least one program, so you must complete this step.

Alternatively, you can set up a program using the Create program endpoint, which takes the following fields:*

*Fields for program setup that are not listed in this table are not applicable to lending.

These are the configurations needed for lending:

• Loan products – Templates used to create loans, standardizing how loans are established.
• Loan adjustments (formerly charge plans) – Additional charges or fees that are attached to loan products, configured with processing codes.
• Penalty plans – Specification of how penalties are applied in the case of past due or early repayments.
• Repayment hierarchy – Defines the order in which payments are applied to loan components in the case of a partial repayment.

The following table summarizes the components of lending on the Pismo platform:

• A component is considered Single if you would normally have only one of them. A component is Multiple if it's normal to have more than one. For example, it's possible for a client to have only one program, but most clients have more than one, so Program is marked as Multiple.

** A component is considered Required if the lending product does not work without it. A component that's not technically required might still be required in practice because of local regulations or business rules.

The following sections describe how to set up these components.

The following sample code shows how to use this endpoint to create a lending program named "Sample_lending_program":

curl --request POST  
     --url <https://sandbox.pismolabs.io/programs/v1/programs/template>  
     --header 'Accept: application/json'  
     --header 'Authorization: Bearer <token value>'  
     --header 'Content-Type: application/json'  
     --data '  
{  
     "timezone": "America/Sao_Paulo",  
     "currency_numeric_code": "986",  
     "name": "Sample_lending_program",  
     "type": "LENDING"  
}'

📘

When you set up a program, you are prompted to accept default processing codes. If you choose not to accept them, then you need to set up your own processing codes. If you don’t accept the default codes or set up your own, your disbursement and repayment requests will return errors.

Set up processing codes

A processing code tells the Pismo platform how to handle a certain type of financial operation. For more information about how the platform uses these codes, refer to Processing codes and transaction types. To create processing codes and map them to transaction types, use the Create processing code endpoint. For more information, refer to Payments configurations.

Configure accounting

The Pismo platform provides tools to keep track of business and financial transactions for accounting purposes. It enables you to create accounting accounts based on your organization's balance sheet. You can then configure accounting scripts that generate accounting entries based on accounting events. For more information, refer to Accounting overview.

Configure interest plans

Interest plans enable you to configure how to charge interest over the life of the loan. You can also apply a penalty when loans are either repaid early (prepayment) or when they fall into arrears.

To create interest plans, use the Create interest plan endpoint. You can use the Create interest plan version endpoint to create a new version of an interest plan.

Configure a repayment hierarchy

If a customer makes a payment that is less than the amount due, the repayment hierarchy determines the order in which the payment is applied to principal, interest, taxes, charges, and fees.

You create a repayment hierarchy using the Create repayment hierarchy endpoint. Other endpoints enable you to get hierarchies.

After you create a repayment hierarchy, you can attach it to one or more loan products. The Create loan product endpoint has a repayment_hierarchy_code field, where you enter the code of the hierarchy that you want to use.

📘

A loan product can have only one repayment hierarchy. The List repayment hierarchies endpoint lists the hierarchies for all your programs.

🚧

There is no default repayment hierarchy. If you don’t assign a repayment hierarchy to a loan product when you create it, borrowers cannot make partial repayments on loans based on that product.

Step 3: Offer loans to customers

When you offer loans, you create loan products, simulate loan scenarios, and book loans into the system.

Create loan products

Loan products in the Pismo platform represent the products that are being offered to end customers, providing a template that incorporates various parameters that control the behavior of loans that are created. You can create loan products with Control Center or the API.

📘

You can use Control Center to create loan products. Refer to Control Center > Lending configurations for more information.

To set up products for loans, use the Create loan product endpoint. Existing configured loan products can be retrieved using the list and get operations.

Step 4: Manage loans day-to-day

Loan management starts with simulating and booking loans. Once the platform has booked the loan, you can move into loan management workflows, including disbursement, repayment, and settlement including early final settlement (EFS).

Simulate loan scenarios

Refer to Simulate loans for information about simulating loans.

Book loans

You cannot re-use booking processing codes once they are sent in a payload to book the loan. Refer to Book a loan for the loan booking steps.

Disburse the loan

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

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.