Products

A Product configuration is the set of terms Loans are issued under: one Archetype, and the values that Archetype admits. It is created by POST /v1/tenants/{tenant_id}/product-configurations, which answers the stored configuration and the version it was written as. A configuration is never edited. A change writes a new version, every earlier version stays readable, and a Loan keeps the version it was issued under. A configuration names no jurisdiction and no borrower. It states the bounds a Loan’s own figures fall inside: the principal range, the two rate corridors, the term menu, the fees and the cadence. Issuance picks one point inside each.

Fields

The fields travel in values, and the Archetype’s frame decides which of them a configuration admits. Every field is optional on the wire, and a missing one is refused by name rather than supplied. Eight fields are required of all three Archetypes.

Field	What it fixes
`principal_min`, `principal_max`	The amounts a Loan’s principal falls between.
`rate_min`, `rate_max`	The corridor the Loan’s ordinary rate is picked from, quoted annually.
`penalty_rate_min`, `penalty_rate_max`	The corridor the Loan’s penalty rate is picked from, quoted annually.
`day_count_basis`	How interest counts days: `actual_360`, `actual_365_fixed` or `30e_360`.
`schedule`	The cadence: `anchored_monthly`, `anchored_every_n_days` with `interval_days`, or `semi_monthly_grid` with `grid_days`.

The penalty corridor is required of all three. A configuration that cannot say what happens when it is not paid does not describe a sellable product. A penalty rate invented at issuance is a term nobody agreed to. Five fields are optional on all three Archetypes.

Field	What it fixes
`origination_fee`	A fee charged at issuance.
`first_period_gap_days`	Days between the anchor and the first due date.
`late_fee`	A flat charge once a Period stands unpaid past its grace.
`grace_days`	Days after the due date before a Period counts overdue.
`early_money_treatment`	What unelected money past every matured Period does.

An absent optional field means the absence rather than a default. No late_fee is no late fee, and no grace_days is no grace. One of the five carries a meaning when absent. early_money_treatment absent is reduces_principal, the statutory prepayment: the law’s answer rather than a value the Platform picked. Its alternative, advances_instalments, settles Periods that have not matured instead.

Archetypes

An Archetype fixes the repayment shape. The set is closed — instalment, bnpl and payday — and no route adds a fourth. The Archetype is chosen when the configuration is created, and a new version carries values alone. The shape a Loan was issued under never changes. Each Archetype adds the fields its shape needs and locks the ones its shape fixes. A locked field is refused with the Archetype’s own reason, and a field of another shape as not part of this frame. Neither is ignored: a value you believe is in force and is not is a dispute waiting for its Loan.

Instalment

An instalment product repays a principal over a menu of terms, and each payment carries principal, interest, fee and tax. It locks nothing: a field this frame refuses is one belonging to another Archetype’s shape. Two fields belong to the instalment frame.

Field	Presence	What it fixes
`terms`	Required	The menu of period counts a Loan is issued for.
`minimum_instalment`	Optional	The payment below which the product is not sold.

An issuance whose quoted payment falls under minimum_instalment answers 422. Nothing adjusts the term or the principal to clear the floor.

Buy Now Pay Later

A bnpl product splits a purchase into instalments and always collects a payment at the purchase itself. That collection is the Archetype’s own invariant, so a BNPL issuance carries a down_payment. Four fields belong to the BNPL frame, and one of them exists to be refused.

Field	Presence	What it fixes
`terms`	Required	The menu of period counts a Loan is issued for.
`minimum_instalment`	Optional	The payment below which the product is not sold.
`merchant_commission_bps`	Optional	The commission between tenant and store, in basis points, signed.
`payment_at_purchase`	Locked	The collection at the purchase, which the Archetype fixes.

The commission is signed because it runs both ways. The store pays the tenant for financing the purchase, or the tenant pays the store for bringing the client. Nothing at issuance or in servicing reads it: the configuration records the commercial term, and settling it with the store is yours.

Pay Day Loan

A payday product carries a single period to one date, and it is the only Archetype whose frame carries the rollover fields. It has no instalment menu, and minimum_instalment is not a field of a payday product. Three fields belong to the payday frame.

Field	Presence	What it fixes
`rollover_limit`	Optional	How often a Loan under this product rolls.
`rollover_fee`	Optional	What one roll costs.
`terms`	Locked	The instalment menu, which a single period does not carry.

Both rollover fields are recorded and read by nothing: no route rolls a Loan over, and none reports one.

Example

The configuration behind every worked example on this site is an instalment product in MXN.

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/product-configurations" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "archetype": "instalment",
    "values": {
      "principal_min": { "minor_units": 100000, "currency": "MXN" },
      "principal_max": { "minor_units": 2000000, "currency": "MXN" },
      "rate_min": "36",
      "rate_max": "60",
      "penalty_rate_min": "36",
      "penalty_rate_max": "90",
      "day_count_basis": "actual_360",
      "schedule": { "kind": "anchored_monthly" },
      "terms": [6, 12, 18],
      "origination_fee": { "minor_units": 25000, "currency": "MXN" },
      "late_fee": { "minor_units": 15000, "currency": "MXN" }
    }
  }'

{
  "id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
  "tenant_id": "t-0001",
  "archetype": "instalment",
  "created_at": "2026-08-18T22:26:41.407349Z",
  "version": 1,
  "values": {
    "principal_min": { "minor_units": 100000, "currency": "MXN" },
    "principal_max": { "minor_units": 2000000, "currency": "MXN" },
    "rate_min": "36",
    "rate_max": "60",
    "penalty_rate_min": "36",
    "penalty_rate_max": "90",
    "day_count_basis": "actual_360",
    "origination_fee": { "minor_units": 25000, "currency": "MXN" },
    "late_fee": { "minor_units": 15000, "currency": "MXN" },
    "terms": [6, 12, 18],
    "schedule": { "kind": "anchored_monthly" }
  }
}

The answer is 201. An issuance names this id as its configuration_id and this version as its configuration_version.

Create a configuration

The endpoint page: every field, every refusal, and a playground that sends the call.

Quickstart

The walk from this configuration to a settled instalment, in six calls.

Versions

Five routes serve the configuration: they create it, list yours, read the latest version, write a new version, and read one version by number. The paths are on API reference, and not one of the five reads a query parameter. Reading the latest and reading one version are separate addresses on purpose. ?version=2 on the read of the latest answers 400: this route does not read the parameter "version". A caller asking for a version is never handed whatever the newest happens to be. A version number counts from 1 and rises by one. The word latest in an issuance’s configuration_version is refused by name.

A new version does not reach an issued Loan. Its Schedule, its amounts and its disclosed cost figure were priced at issuance, and nothing recomputes them.

Limits

The Platform’s own bounds are headroom, not policy. They catch a typo or an overflow. What is lawful to sell is your compliance question, and a configuration names no jurisdiction for the Platform to test it against.

Bound	Value
Rate corridor, ordinary and penalty	0 to 2,000% per year
Merchant commission	−100% to 100%
Term, in periods	1 to 480
Entries in the term menu	24
`first_period_gap_days`	0 to 365
`rollover_limit`	0 to 52
`grace_days`	0 to 90
`interval_days` on `anchored_every_n_days`	1 to 365

Restrictions

Presence is read from the keys of values, not from what they decoded to. "terms": [] and "terms": null both count as stated, so a locked field spelled empty is refused rather than quietly accepted.

{
  "archetype": "payday",
  "values": {
    "terms": []
  }
}

{
  "error": "product: field is fixed by the archetype: terms on a payday product: a payday product is a single period and carries no instalment menu"
}

A configuration is submitted whole and rejected whole. The first failure stops the walk and names its field, so a body carrying two problems reports one. Fixing it reports the next. These are the refusals, each 422:

a field the Archetype does not carry, and a field the Archetype locks, told apart by the message
a required field the frame declares and the body omits
a value outside a bound above
a minimum above its maximum, in either corridor or in the principal range
amounts in two currencies inside one configuration
an empty term menu where the frame requires one, or the same term offered twice
a rate quoted other than annually, or in a form that is not an exact decimal percentage
a schedule carrying another kind’s parameters: an interval on anchored_monthly, grid days on anchored_every_n_days
a semi_monthly_grid of fewer than two days, of a day outside the month, or of a day repeated

A configuration belonging to another Tenancy answers 404, the same as one that never existed. Any query parameter on any of the five routes answers 400.

Getting started

Authentication

Lending

Fields

Archetypes

Instalment

Buy Now Pay Later

Pay Day Loan

Example

Create a configuration

Quickstart

Versions

Limits

Restrictions

​Fields

​Archetypes

​Instalment

​Buy Now Pay Later

​Pay Day Loan

​Example

Create a configuration

Quickstart

​Versions

​Limits

​Restrictions

Fields

Archetypes

Instalment

Buy Now Pay Later

Pay Day Loan

Example

Versions

Limits

Restrictions