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.
| 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
}
}
Updated about 1 year ago