You can book a loan by finalizing the borrower’s approval and officially creating the loan, which makes the loan active and ready for them to use.

Prerequisites

Before booking a loan, you must show a potential borrower the loan terms though a loan simulation. Once they agree to the terms and conditions, you reference this simulation in the payload when booking the loan. For more information, refer to Simulate loans.

Book a loan

Use the Book loan endpoint to book a loan with a payload that includes the required account_id, installment_plan_id, loan_product_id, and number_of_installments values:

{
  "account_id": 514751581,
  "loan_product_id": "0ea4fe62-5512-4494-baf5-13a3044b7f7b",
  "installment_plan_id": "PL-20250708200752",
  "number_of_installments": 5,
  "metadata": {
    "risk_factor": "low"
  }
}

A successful request returns a loan_id and the loan status transitions to ACTIVE or BOOKED depending on configuration. You can later retrieve the loan_id with listing or individual retrieval endpoints. The Pismo platform generates a Loan booked event:

{
    "org_id": "TN-89e56522-726a-453e-ba6d-796b03245128",
    "external_id": "cca6041c-b57d-44cf-a203-eeea22723878",
    "loan_id": "ded913af-abc9-4769-b179-068ed6181ec5",
    "status": "BOOKED",
    "loan_product_id": "0ea4fe62-5512-4494-baf5-13a3044b7f7b",
    "account_id": 514751581,
    "amount": 1000.0,
    "start_date": "2026-05-24",
    "created_at": "2026-05-24T21:34:47"
}

Troubleshooting

Use this section to troubleshoot errors that can occur when booking a loan and understand how to resolve them.

Because the Book loan endpoint is asynchronous, it returns 202 Accepted with a loan_id while booking. Meanwhile, interest calculation and authorization continue in the background.

Common problems can fall into two groups: validation and authorization errors returned synchronously as a 400 or 500 before the 202, and problems that surface only after the 202, which you diagnose by inspecting the loan and its events.

What does the ELND0004 Authorization failed error mean?

Booking authorizes the loan against the account, and this 400 means that authorization was denied. The response includes response_code and denial_code values that identify the reason:

{
  "code": "ELND0004",
  "message": "Authorization failed",
  "response_code": "62",
  "denial_code": "IAD"
}

Common causes are an account status that doesn't permit the posting, insufficient limits, or an anti-fraud rejection.

To resolve:

1. Read the denial_code and response_codeto identify the reason.
2. Retrieve the loan with Get loan to confirm its state.
3. Check the account's status and limits, and confirm the account_id in the payload matches the account you intend to debit.
4. Correct the reason for the denial and retry the booking.

Why did booking fail with a validation error (ELND0002, ELND0003, or ELND0005)?

These 400 errors mean the request failed validation before booking started:

• ELND0002—a required header or body field wasn't passed.
• ELND0003—a body field was passed but isn't valid.
• ELND0005—a referenced entity (related data) couldn't be found.

A frequent cause of ELND0005 is a loan_product_id that belongs to a different organization (tenant), or a number_of_installments value that the referenced installment plan doesn't offer.

To resolve:

1. Confirm all required fields are present: account_id, loan_product_id, installment_plan_id, and number_of_installments.
2. Verify the loan product resolves for your tenant using Get loan product. If it returns a "Not found" error, the loan_product_id or the tenant header is mismatched.
3. Confirm number_of_installments matches one of the installment counts your simulation offered for that plan.

What can I do if the simulation or installment plan has expired?

Loan booking references a loan simulation, and loan simulations are valid for one day only. If the simulation has expired, you can't book against it. The system is designed to always reflect current rates, fees, and balances.

If the customer still wants the loan, create a new simulation with Create simulation and use the new installment_plan_id for booking. If the simulation applies an unexpected plan ID, verify the account, program, and organization simulation attachments. Refer to Simulate loans for the full configuration-resolution procedure.

Why is my loan BOOKED but not ACTIVE?

A successful booking transitions the loan to BOOKED or ACTIVE depending on the loan product's configuration, so a loan resting at BOOKED may be correct rather than a failure. The loan_activation_method on the loan product determines when the loan becomes ACTIVE; for example, on booking, on disbursement, or on repayment.

To resolve:

1. Review what each status represents in Loan statuses overview.
2. Check the loan product's activation method with Get loan product; refer to Create loan products for how the activation method is configured.
3. If the method expects a later trigger (such as disbursement), the loan correctly remains BOOKED until that event occurs.

Booking returned 202 Accepted but the loan never becomes active

Because booking is asynchronous, the 202 is returned before booking and authorization finish. If the loan never reaches BOOKED or ACTIVE:

1. Retrieve the loan with Get loan and check its status. A "Not found" response means the loan was never persisted so you must recheck the payload and retry.
2. Confirm the platform generated both the Loan booked and Platform authorization created events. When you are missing an authorization event you can check if the authorization leg failed.
3. Track subsequent status changes through the Lending loan update event.
4. Correlate all requests and events by noting the x-cid. If you receive a 500 ELND0001 (unexpected error), check the x-cid and escalate to Pismo support.