Create a loan

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.

FieldDescription
product_nameThe name of the loan product.
product_typeThe type of loan product. To create a personal loan product, use PERSONAL.
currencyThe currency the loan product uses.
collateralShows whether there’s collateral involved on a loan product. For personal loans, use none.
repayment_calculation_methodThe repayment method the loan product uses.
interest_typeSpecifies whether the loan product uses simple or compound interest.
days_in_year_methodThe days in year method the loan product uses.
repayment_frequencyThe frequency of how often a borrower needs to repay a loan.
disbursementThe disbursement method the loan product uses.
stagesThe 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 loan booking endpoint.

This API request example includes these fields.

FieldDescription
product_idThe ID of a personal loan product. This is a required field.
loan_amountThe total amount of the personal loan.
start_dateThe starting date of the personal loan.
stagesThe personal loan interval details, such as interest rate and how often repayments occur.
disbursement.due_dateThe 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 Get loan simulation 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 loan booking endpoint to book the loan.

This API request example includes these required fields.

FieldDescription
loan_simulation_idThe ID of the simulated personal loan with the payment schedule.
account_idThe 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 loan endpoint. The interval between booking and disbursing a personal loan depends on your lending rules.

This API request example includes these required fields.

FieldDescription
disbursement_dateThe date to disburse the personal loan. You can find this date in the loan simulation.
disbursement_amountThe amount disbursed for the personal loan. You can find this amount in the loan simulation.
disbursement_accountThe 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.

FieldDescription
product_nameThe name of the loan product.
product_typeThe type of loan product. For a BNPL loan product, use BNPL.
currencyThe currency the loan product uses.
collateralShows whether there’s collateral on a loan. For BNPL loans, use none.
repayment_calculation_methodThe repayment method the loan product uses.
interest_typeSpecifies whether the loan product uses simple or compound interest.
days_in_year_methodThe days in year method the loan product uses.
repayment_frequencyThe frequency of how often a borrower needs to repay a loan.
disbursementThe disbursement method the loan product uses.
stagesThe 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 loan booking endpoint.

This API request example includes these fields.

FieldDescription
product_idThe ID of a BNPL loan product. This is a required field.
loan_amountThe total amount of the BNPL loan.
start_dateThe starting date of the BNPL loan.
stagesThe BNPL loan interval details, such as interest rate and how often repayments occur.
disbursement.due_dateThe 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 Get loan simulation 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 loan booking endpoint to book the loan.

This API request example includes these required fields.

FieldDescription
loan_simulation_idThe ID of the simulated BNPL loan with the payment schedule.
account_idThe 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 loan endpoint. The interval between booking and disbursing a BNPL loan depends on your lending rules. This API request example includes these required fields.

FieldDescription
disbursement_dateThe date to disburse the BNPL loan. You can find this date in the loan simulation.
disbursement_amountThe amount disbursed for the BNPL loan. You can find this amount in the loan simulation.
disbursement_accountThe 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
   }
}