Simulate loans

What is loan simulation?

Loan simulation lets you preview the terms of a loan before booking it. When you create a simulation, the Pismo platform calculates a payment schedule, interest, and other terms based on the loan product configuration and the parameters you provide. This helps you and your customers understand repayment amounts, due dates, and total costs before committing to a loan.

How does the platform select a simulation plan?

When you request a simulation, the Pismo platform selects a plan using the following priority:

1. Account-level settings (highest priority)
2. Program-level settings
3. Organization-level settings (lowest priority)

The simulation system loads all available plans and tries to match them to your request. The selection process follows this order:

• If you provide specific plan IDs, the simulation system looks only for those plans. If none match, no plan is selected.
• If you provide custom filters (but no plan IDs), the simulation system looks for plans with at least one matching filter value. If none match, selection fails.
• If you provide neither plan IDs nor custom filters, the simulation system applies standard filters (such as processing codes or merchant IDs) and checks for matches.

If no plans match after applying these rules, the system returns a message indicating that no plan was selected with the provided plan IDs or filters. This means your request did not match any configured simulation plans.

Simulate a loan

Before you book a loan, you begin by using a loan product to simulate the booking. If the customer does not agree to the terms and conditions shown in the simulation, you have the option of simulating another loan (using a different loan product). If the customer agrees to the terms and conditions, you use the simulation to book the loan. How the funds are disbursed (in one lump sum or in stages) is determined by how you set up the loan product, but you need to call the Disburse loan endpoint to perform the actual disbursal. A simulation is valid for one day.

To simulate a loan booking, use the Create simulation endpoint.

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": "2026-06-24",
  "stages": [
    {
        "interest_rate":{
            "value": 0.12,
            "unit": "YEAR"
        },
        "period": {
            "value": 3,
            "unit": "MONTH"
        }
    }
  ],
  "disbursement": [
    {
      "due_date": "2026-06-24"
    }
  ]
}

Your system sends a POST to payment-methods-admin/v1/simulations with the following payload:

{
  "authorization_mode": "CREDIT"
}

The Pismo platform generates the Loan simulation created event:

{  
	org_id: "89e56522-726a-453e-ba6d-796b03245128",  
	simulation_id: "afedc8b0-86b2-41ca-87a3-3481df17261b",  
	product_id: "BNPL_PRODUCT_2022",  
	product_version: "1",  
	loan_amount: 1000.0,  
	start_date: "2022-10-24",  
	disbursement_schedule: [  
		"2022-10-24",  
		"2022-11-24",  
		...  
	],  
	stages: \[  
		{  
			period: 12,  
			interest_rate:  
				{  
					unit: "YEAR",  
					value: 0.12  
				}  
		},  
		...  
	}  
}

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": "2026-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": "2026-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": "2026-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": "2026-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": "2026-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.

Troubleshooting

Read this section to determine what's causing errors or confusion about a loan simulation.

Why is the calculation or plan retrieved not what I expected?

If the simulation returns an unexpected plan or calculation, it may be due to configuration at a different level (account, program, or organization). For example, if an account has a specific plan attached, it overrides program or organization-level plans.

To resolve:

1. Verify all active plan attachments using the relevant GET endpoints:
   • Get organization simulation config
   • Get program simulation config
   • Get account simulation config
2. Check which configuration level is being applied.
3. Retrieve the simulation configuration using the GET simulation config endpoint.

Update or remove conflicting attachments as needed.

What does the MISSING_SIMULATION_CONFIG error mean?

This error means no valid simulation configuration was found for the account, program, or organization. The system cannot load any simulation plan.

To fix this:

1. Verify all active attachments using the GET endpoints for organization, program, and account simulation configs.
2. Check which configuration level is being applied.
3. Retrieve the simulation configuration using the GET simulation config endpoint.

Update your configuration to ensure at least one valid simulation plan is attached.

Why can't I simulate a down payment as the first installment?

If you want the first installment to act as a down payment, be aware of a limitation:

• The first installment calculated by the simulation includes interest. A down payment should not include interest.
• If you use the first installment as a down payment and keep the contract total unchanged, the customer may pay interest on the down payment, resulting in an incorrect contract value.
• In some cases, this can make the contract value negative.

To avoid this, do not use the first installment as a down payment unless your configuration and calculation method support it. Review your simulation parameters and contract structure.

For more information, refer to the Lending API reference.