Skip to main content
A loan is an agreement with one client under one product: the amount, the rate, the term and the date it runs from. You state those terms once, and the Platform turns them into a repayment plan, a disclosed cost and a record that every later payment and act is applied to. Before you issue one you need a product to issue it under and a registered client to issue it to. A loan is never edited. What happens after issuance is recorded as facts against it: payments arrive, a period goes overdue, a rollover is granted, a cancellation is recorded. The Platform derives the loan’s state from those facts every time you read it, so the state you see and the record behind it can never disagree.

​
Preview, then issue

A preview is a quote. It takes the same body as an issuance, checks it the same way and prices it the same way, but records nothing. Use it to show the borrower the plan before they sign.

Preview the terms

Post the terms to the preview route. The answer is the full plan: every payment with its dates and amounts, the totals they sum to, and the disclosed cost figure.

Issue the loan

Post the same body to the loans route, plus a reference of your own. The answer is the loan, carrying the plan the preview showed.

Keep the id

Every later call about the loan names its id. Your reference makes a retry safe: repeating the request with the same reference returns the same loan.
State what a plan costs from totals, never from a sum of your own. An offer that sells a menu of terms is one preview per term, and a term the principal cannot be divided across at this rate is refused rather than rounded.
Repeating an issuance with the same reference and the same body answers 200 with the loan already on file. The same reference with a different body answers 409, naming the field that differs. A mistyped reference on a new deal never disburses against an old loan.
Issue with the loans endpoint, and quote with the preview endpoint. The API reference carries the exact format and the error each value returns.

​
What issuance checks

Every value in the body is checked against the product it names and the jurisdiction it declares. The first problem stops the check and names its field. A preview runs the same checks, so a preview that passes is an issuance that passes.
The last check is the one that moves. The Platform holds dated holiday data for each market, and a loan whose schedule runs past the last covered day is refused today and may be issuable after a later release. See Markets for the current horizon.

​
What is frozen

Issuance prices the agreement once and keeps everything the pricing read. A later change to the product, to a holiday calendar or to a market rule does not reach a loan already issued.
Read back on every call. Nothing on the Platform rewrites them.
A new version of the product changes nothing here.
A holiday declared after issuance does not move a date. A rollover adds a segment to the serviced schedule and leaves this plan as issued.
The penalty rate, the late fee, the tolerance, what penalty accrues on, and when acceleration is allowed. Two loans issued a year apart under the same market can lawfully differ, because each carries the rule as it stood on its own day.
In Mexico this is the CAT. It excludes tax, as the rule requires, and it never changes.

​
A worked example

The loan issued above is MXN 8,000.00 over 12 months at 45.5% a year, under a product with a MXN 250.00 origination fee and 16% tax on interest and fee. This is the plan the Platform stores for it. Reading the rows:
  • The payment is equal. Every period pays 900.66, and the split between principal and interest moves: interest falls as the balance falls, and principal rises to keep the payment level. The last period pays 900.78, twelve centavos more, because the Platform keeps the rounding residue of the whole plan and settles it there instead of spreading a centavo nobody can trace.
  • Interest counts actual days. Period 1 runs from 2 March to 2 April, 31 days, on the actual_360 basis: 8,000.00 × 45.5% × 31 ÷ 360 = 313.44. Period 2 runs 30 days on a smaller balance, so it charges 283.88.
  • The fee is spread evenly. 250.00 over 12 periods is 20.83 a period, and the last four carry 20.84 so the twelve add up to exactly 250.00. Nothing accrues on the fee.
  • Tax follows the rule the loan states. 16% of interest plus fee: in period 1, 16% of 313.44 + 20.83 = 53.48. The tax column above shows fee and tax together, 20.83 + 53.48 = 74.31.
  • Due dates move, scheduled dates do not. Every period is scheduled on the 2nd. Four of them fall due later: 2 April 2026 is Holy Thursday, so period 1 is due Monday the 6th; 2 August is a Sunday; 2 November is Día de Muertos; 2 January 2027 is a Saturday. Interest runs between the scheduled dates, so a moved due date changes what the borrower has to pay by, never what they pay.
Over the whole plan the borrower pays 10,808.04: the 8,000.00 principal, 2,170.78 of interest, 250.00 of fee and 387.26 of tax. The disclosed cost figure, 64.9%, is computed from these flows without the tax, as the Mexican rule requires.
Preview this loan yourself: send the body from Preview, then issue to the preview route and compare. A preview is priced by the same code that issues, so the twelve rows come back identical.

​
Read a loan

One call returns the whole record: the frozen terms and plan, every recorded event, and the state derived from them.
Read a loan
Beyond the frozen blocks above, the answer carries the derived state, every recorded event in events with the day it is about and the moment it was written, any anomalies the Platform resolved instead of refusing, and rolled_over, how many rollovers stand in force. A closed loan adds closed_on; a written-off loan adds write_off. The read endpoint describes each field.

​
States

A state names what the recorded facts add up to. No state is final: each names the fact that withdraws it. A settlement for less closes a loan too: it reads closed, with what was forgiven stated on the read.
When facts pile up, precedence decides: voided over held over cancelled over rescinded and withdrawn over ceded over written_off over closed over restructured over active. A loan nobody owes cannot be anything else; a loan that never began cannot have been paid off, charged off or sold.

​
List loans

The loans route returns every loan of your tenancy as summary rows, each with its state. Three filters narrow it. Each row carries the contract as issued and paid, what receipts have settled against the loan so far.
Loop while cursor is present. State is derived, not stored, so a page under ?state= can come back short or empty and still carry a cursor. The listing ends only when a page arrives without one.

​
Acts

Nine acts change a loan’s life. Each one is recorded as a fact, never edited. Recording answers 201, an identical retry answers 200, and the same reference with a different body answers 409. Every act is posted under the loan, at its own segment. Every act states on, the day it is about — a suspension states from and to instead — and the same three fields of your own: reference, your name for the act, unique across all nine acts of your tenancy; actor, your reference for whoever acted; and basis, what they wrote down about why. An optional context object is stored and returned beside the fact.
An act is permanent. What withdraws one is another fact, a retraction of that event, and the withdrawn act stays readable among the loan’s events.

​
Cancel a loan

A cancellation is your record that the agreement never began: signed in error, or never disbursed. The date may not fall before the loan’s anchor.
Record a cancellation
The loan answers with state: "cancelled" and a new cancelled event that carries your reference, actor and basis. Everything else reads exactly as issued. A cancellation says the loan never began, so any fact that says otherwise refuses it.

​
Roll a Pay Day Loan over

A rollover is the borrower paying the cost accrued so far instead of repaying the loan, and carrying the principal forward onto one more period on the same terms. You record it on the date the borrower stood at the till.
Record a rollover
What happens on the loan:
  • The loan stays active, keeps its id, its terms and its disclosed cost, and rolled_over goes up by one.
  • A settlement falls due on the rollover date: the interest accrued to that day, the product’s rollover_fee, and the tax on both. It carries no principal.
  • A new segment starts on that date with the same shape as the original term. The principal and the uncollected share of the origination fee move onto it.
  • The issued plan is untouched. The segment appears on the serviced schedule.
Recording a rollover does not collect the settlement. Report the money as a receipt with the rollover date as its value date, the way you report every other payment. Left unreported, the settlement goes overdue the next day and accrues the late fee.
A rollover is refused when the loan is not in a position to carry a balance forward.
Rollover is provisional pending Mexican counsel. The Platform enforces the conservative reading: the settlement is paid in money and never capitalised, an overdue loan is not rolled, and the count is bounded where the product states a bound. Read Lending in Mexico before selling the operation.
Delinquency covers acceleration and write-off, and Correcting mistakes covers retraction and what it cannot undo. A refused issuance answers 422 and names its field; a refused act answers 409 and names the fact in the way. Every code is on Errors.

​
FAQ

No. A loan is never edited. What you can do is record a fact against it: a payment, a cancellation, a rollover, a retraction of a fact recorded in error. A loan agreed on the wrong terms is cancelled and issued again.
Yes. The anchor is the day the agreement runs from and is never compared with a clock. A loan signed on Friday and reported on Monday is a fact about Friday, and its plan runs from Friday.
With the same reference and the same body, the second call answers 200 with the loan already on file. Nothing is written twice. With the same reference and a different body, it answers 409 reference_reused and names the field that differs.
No. A preview records nothing. But the issuance is priced by the same code on the same inputs, so the plan it returns is identical to the preview’s, down to the centavo.
As long as the product’s terms menu allows and the holiday calendar covers. Every date of the plan has to fall on or before the last day the Platform holds holiday data for, otherwise the issuance answers 422 beyond_horizon. The horizon moves out with each release. See Markets.
No. It keeps its id, its terms, its product version and its disclosed cost, and rolled_over counts one more. The rollover adds a segment to the serviced schedule and leaves the issued plan as it was.