Create a loan

How you can create loans using the Pismo platform

The following shows you how to create a loan on the Pismo platform. For information about the loan lifecycle, see Pismo lending lifecycle.

Personal loan

A personal loan is a type of unsecured loan product offered for individual borrowers where the funds have no predestined use.

Create personal loan product

To create a personal loan product, use the Create loan product endpoint. The API request example includes these required fields.

Field

Description

product_name

The name of the loan product.

product_type

The type of loan product. To create a personal loan product, use PERSONAL.

currency

The currency the loan product uses.

collateral

Shows whether there’s collateral involved on a loan product. For personal loans, use none.

repayment_calculation_method

The repayment method the loan product uses.

interest_type

Specifies whether the loan product uses simple or compound interest.

days_in_year_method

The days in year method the loan product uses.

repayment_frequency

The frequency of how often a borrower needs to repay a loan.

disbursement

The disbursement method the loan product uses.

stages

The loan interval details, such as interest rate and how often repayments occur.

{
    "product_name": "Personal Loan Example",
    "product_type": "PERSONAL",
    "currency": "400",
    "collateral": "none",
    "loan_type": "fixed_rate",
    "repayment_calculation_method": "ei_reducing_balance",
    "interest_type": "simple",
    "days_in_year_method": "actual_actual",
    "repayment_frequency": {
        "method": "monthly"
    },
    "disbursement": {
        "method": "simple"
    },
    "stages": [
        {
            "repayment_mode": {
                "type": "PRINCIPAL_AND_INTEREST"
            }
        }
    ],
    "rules": {
        "loan_amount": {
            "min": 2000,
            "max": 100000
        },
        "loan_term": {
            "min": {
                "value": 6,
                "unit": "month"
            },
            "max": {
                "value": 36,
                "unit": "month"
            }
        },
        "interest_rate": {
            "min": {
                "value": 6,
                "unit": "year"
            },
            "max": {
                "value": 40,
                "unit": "year"
            }
       ,
        "installment_number": {
            "min": 1,
            "max": 12
        }
 
    }
}

After you create the personal loan product, the API response returns the product_id. Use this ID to simulate a loan.

{
    "product_id": "5c355ddf-a2c6-4a8e-9661-f53a19fad264"
}

Simulate the personal loan

After you create the loan product, you can start offering personal loans to your borrowers.

For example, when a borrower needs to cover an unforeseen expense, you can offer them a personal loan from an existing loan product. To offer a personal loan, use the Simulate a loan booking endpoint.

This API request example includes these fields.

Field

Description

product_id

The ID of a personal loan product. This is a required field.

loan_amount

The total amount of the personal loan.

start_date

The starting date of the personal loan.

stages

The personal loan interval details, such as interest rate and how often repayments occur.

disbursement.due_date

The date when to disburse the personal 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 personal 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 personal 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 personal loan

After the borrower accepts the terms of the personal loan from the simulation, use the Create a loan booking endpoint to book the loan.

This API request example includes these required fields.

Field

Description

loan_simulation_id

The ID of the simulated personal loan with the payment schedule.

account_id

The 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 personal 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 personal loan

After the borrower agrees to book the personal loan, use the Disburse a loan endpoint. The interval between booking and disbursing a personal loan depends on your lending rules.

This API request example includes these required fields.

Field

Description

disbursement_date

The date to disburse the personal loan. You can find this date in the loan simulation.

disbursement_amount

The amount disbursed for the personal loan. You can find this amount in the loan simulation.

disbursement_account

The account on the Pismo platform where to disburse the personal loan funds.

{
 "disbursement_date": "2022-06-24",
 "disbursed_amount": 1000.00,
 "disbursement_account": {
   "type": "INTERNAL",
   "account_id": 103614168
 }
}

After you disburse the personal 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
   }
}

Buy Now and Pay Later (BNPL)

A BNPL is a type of unsecured loan product that’s typically used by borrowers to pay for items at the point of sale. It often involves a smaller number of installments, smaller loan amounts, and funds directed to the seller of the item.

Create the BNPL loan product

To create a BNPL loan product, use the Create loan product endpoint.

The API request example includes these required fields.

Field

Description

product_name

The name of the loan product.

product_type

The type of loan product. For a BNPL loan product, use BNPL.

currency

The currency the loan product uses.

collateral

Shows whether there’s collateral on a loan. For BNPL loans, use none.

repayment_calculation_method

The repayment method the loan product uses.

interest_type

Specifies whether the loan product uses simple or compound interest.

days_in_year_method

The days in year method the loan product uses.

repayment_frequency

The frequency of how often a borrower needs to repay a loan.

disbursement

The disbursement method the loan product uses.

stages

The loan interval details, such as interest rate and how often repayments occur.

{
    "product_name": "Retailer X BNPL for Checkout",
    "product_type": "BNPL",
    "currency": "400",
    "collateral": "none",
    "loan_type": "fixed_rate",
    "repayment_calculation_method": "ei_reducing_balance",
    "interest_type": "simple",
    "days_in_year_method": "actual_actual",
    "repayment_frequency": {
        "method": "monthly"
    },
    "disbursement": {
        "method": "simple"
    },
    "stages": [
        {
            "repayment_mode": {
                "type": "PRINCIPAL_AND_INTEREST"
            }
        }
    ],
    "rules": {
        "loan_amount": {
            "min": 100, 
            "max": 2000 //BNPL Transactions usually aren`t larger than 2000 USD
        },
        "loan_term": {
            "min": {
                "value": 1,
                "unit": "month"
            },
            "max": {
                "value": 6, // BNPL usually doesn`t last for more than 6 months
                "unit": "month"
            }
        },
        "interest_rate": {
            "min": {
                "value": 0,  // Not charging interest or low interest rates to the installments are common practice for BNPL Loans
                "unit": "month"
            },
            "max": {
                "value": 20,
                "unit": "month"
 
            }
        },
        "installment_number": {
            "min": 1,
            "max": 12
        }
 
    }
}

After you create the BNPL loan product, the API response returns the product_id. Use this ID to simulate a loan.

{
    "product_id": "788c0105-2662-4a69-bf23-96c460ee25bb"
}

Simulate the BNPL loan

After you create the loan product, you can start offering BNPL loans to your borrowers.

For example, when a borrower needs to pay off a purchase, you can offer them a BNPL loan from an existing loan product. To offer a BNPL loan, use the Simulate a loan booking endpoint.

This API request example includes these fields.

Field

Description

product_id

The ID of a BNPL loan product. This is a required field.

loan_amount

The total amount of the BNPL loan.

start_date

The starting date of the BNPL loan.

stages

The BNPL loan interval details, such as interest rate and how often repayments occur.

disbursement.due_date

The date when to disburse the BNPL 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 BNPL 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 BNPL 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 BNPL loan

After the borrower accepts the terms of the BNPL loan from the simulation, use the Create a loan booking endpoint to book the loan.

This API request example includes these required fields.

Field

Description

loan_simulation_id

The ID of the simulated BNPL loan with the payment schedule.

account_id

The 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 BNPL 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 BNPL loan

After the borrower agrees to book the BNPL loan, use the Disburse a loan endpoint. The interval between booking and disbursing a BNPL loan depends on your lending rules. This API request example includes these required fields.

Field

Description

disbursement_date

The date to disburse the BNPL loan. You can find this date in the loan simulation.

disbursement_amount

The amount disbursed for the BNPL loan. You can find this amount in the loan simulation.

disbursement_account

The account on the Pismo platform where to disburse the loan funds.

{
 "disbursement_date": "2022-06-24",
 "disbursed_amount": 1000.00,
 "disbursement_account": {
   "type": "INTERNAL",
   "account_id": 103614168
 }
}

After you disburse the BNPL 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
   }
}

Did this page help you?