Quickstart

Six calls take an empty sandbox Tenancy to an issued Loan with its first instalment settled. At the end you hold a Loan on record, the Schedule the borrower repays it over, and one instalment reported as paid. Nothing here is real money: a sandbox Tenancy owes nobody, and every call is safe to repeat. The walk stays in one shell. If a term in it is new, Concepts defines it, and no definition is repeated here.

Prerequisites

Two things exist before the first call, and the walk creates everything else.

Requirement	Value
Tenancy kind	`sandbox`: its records stand for nothing, and every operation is permitted.
Credential	A key of `write` scope for that Tenancy, minted by an administrator at the Console.

What each kind permits is on Sandbox and live. The objects the calls create are defined on Concepts, and no field table is reproduced here. Every call goes to https://api.capcells.com, which stops before /v1. Snippets read two shell variables: $TENANT_ID names your Tenancy, and $CAPCELLS_API_KEY carries the key, presented as a bearer token.

Issue a Loan

Four calls turn terms into an agreement on record.

Create the configuration

Create the terms you sell. The frame of the instalment Archetype decides which fields values must carry, and refuses any field it does not admit by name.

Create the configuration

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" }
    }
  }'

Response

{
  "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: version is 1, and id is the value an issuance names as its configuration_id.

Register the Client

Register the identifier the Loan will name. A Client carries an identifier, an optional label and nothing else. A field for a name, a birth date or a document is refused by name.

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/clients" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "c-0001", "label": "contract-0001" }'

Response

{
  "id": "c-0001",
  "tenant_id": "t-0001",
  "label": "contract-0001",
  "created_at": "2026-08-18T22:26:41.410593Z"
}

The answer is 201, and the issuance body names this id as its client_id.

Preview the Loan

Quote the agreement before recording it. A preview reads the body an issuance takes, without its reference, and records nothing. The wire form of every value is on Model.Every figure here comes from one Loan: MXN 8,000.00 over 12 Periods at "45.5" per year, anchored 2026-03-02 in MX. It runs on the configuration above, under its actual_360 day count. Its penalty_rate is "60", and tax runs at 16% on interest, fee, penalty and late fee.

Preview the Loan

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/preview" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "c-0001",
    "configuration_id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
    "configuration_version": 1,
    "principal": { "minor_units": 800000, "currency": "MXN" },
    "term_periods": 12,
    "rate": "45.5",
    "penalty_rate": "60",
    "anchor": "2026-03-02",
    "jurisdiction": "MX",
    "tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
  }'

Response

{
  "configuration": { "id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645", "version": 1 },
  "terms": {
    "client_id": "c-0001",
    "principal": { "minor_units": 800000, "currency": "MXN" },
    "term_periods": 12,
    "rate": "45.5",
    "penalty_rate": "60",
    "anchor": "2026-03-02",
    "jurisdiction": "MX",
    "tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
  },
  "periods": [
    {
      "index": 1,
      "scheduled_on": "2026-04-02",
      "due_on": "2026-04-06",
      "principal": { "minor_units": 51291, "currency": "MXN" },
      "interest": { "minor_units": 31344, "currency": "MXN" },
      "fee": { "minor_units": 2083, "currency": "MXN" },
      "tax": { "minor_units": 5348, "currency": "MXN" },
      "payment": { "minor_units": 90066, "currency": "MXN" }
    },
    {
      "index": 2,
      "scheduled_on": "2026-05-02",
      "due_on": "2026-05-04",
      "principal": { "minor_units": 54720, "currency": "MXN" },
      "interest": { "minor_units": 28388, "currency": "MXN" },
      "fee": { "minor_units": 2083, "currency": "MXN" },
      "tax": { "minor_units": 4875, "currency": "MXN" },
      "payment": { "minor_units": 90066, "currency": "MXN" }
    },
    …
    {
      "index": 12,
      "scheduled_on": "2027-03-02",
      "due_on": "2027-03-02",
      "principal": { "minor_units": 84204, "currency": "MXN" },
      "interest": { "minor_units": 2980, "currency": "MXN" },
      "fee": { "minor_units": 2084, "currency": "MXN" },
      "tax": { "minor_units": 810, "currency": "MXN" },
      "payment": { "minor_units": 90078, "currency": "MXN" }
    }
  ],
  "disclosure": { "jurisdiction": "MX", "figure": "64.9" },
  "regime": {
    "penalty_rate": "60",
    "late_fee": { "minor_units": 15000, "currency": "MXN" },
    "grace_days": 0,
    "penalty_base": "overdue_principal",
    "capitalises": false,
    "acceleration": { "forbidden": false, "missed_periods": 3, "notice_days": 15 }
  }
}

Nine of the twelve period rows are cut above; disclosure.figure carries the CAT, and nothing was recorded. The quoted payment of 90066 (MXN 900.66) rounds down to a whole centavo; the final Period’s 90078 absorbs the 12-centavo residual.

Issue the Loan

Issue under the same body, now carrying its reference: your own identifier for this agreement, unique within the Tenancy.

Issue the Loan

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "loan-0001",
    "client_id": "c-0001",
    "configuration_id": "d57bfbfb-7703-4d87-8a0e-94d4200d3645",
    "configuration_version": 1,
    "principal": { "minor_units": 800000, "currency": "MXN" },
    "term_periods": 12,
    "rate": "45.5",
    "penalty_rate": "60",
    "anchor": "2026-03-02",
    "jurisdiction": "MX",
    "tax": { "rate": "16", "on": ["interest", "fee", "penalty", "late_fee"] }
  }'

Response

{
  "id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
  "tenant_id": "t-0001",
  "state": "active",
  "created_at": "2026-08-18T22:26:41.420114Z",
  …
}

The answer is 201 and state answers active; the body continues with the recorded events and the preview’s document, priced once at issuance. A retry carrying the same reference and the same statements answers 200 and this same Loan.

Preview and issue read one body. A preview ignores reference and records nothing; an issuance retried under its reference answers 200 with the Loan on file, not a second Loan.

Report the money

You hold the funds: money is reported as a Receipt against the Client, and every figure after it is derived.

Report the Receipt

Report the first instalment as it arrives. Period 1 is scheduled on 2026-04-02, a non-working day in MX, so collection moved to 2026-04-06, the value date the borrower pays on.

Report the Receipt

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/receipts" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "receipt-0001",
    "client_id": "c-0001",
    "amount": { "minor_units": 90066, "currency": "MXN" },
    "value_date": "2026-04-06"
  }'

Response

{
  "receipt": { … },
  "rule": {
    "jurisdiction": "MX",
    "charge_order": ["penalty", "late_fee", "fee", "interest", "principal"],
    "period_order": "oldest first",
    "undesignated_loans": "most_onerous_then_oldest"
  },
  "settled": { "minor_units": 90066, "currency": "MXN" },
  "residual": { "minor_units": 0, "currency": "MXN" },
  "excess": { "minor_units": 0, "currency": "MXN" },
  "loans": [
    {
      "loan_id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
      "reference": "loan-0001",
      "chosen_by": "default_rule",
      "settled": { "minor_units": 90066, "currency": "MXN" },
      "prepayment": { "minor_units": 0, "currency": "MXN" },
      "residual": { "minor_units": 0, "currency": "MXN" },
      "owed_back": { "minor_units": 0, "currency": "MXN" },
      "periods": [
        {
          "index": 1,
          "due_on": "2026-04-06",
          "total": { "minor_units": 90066, "currency": "MXN" },
          "charges": [
            { "charge": "fee", "amount": { "minor_units": 2083, "currency": "MXN" }, "tax": { "minor_units": 333, "currency": "MXN" }, "total": { "minor_units": 2416, "currency": "MXN" } },
            { "charge": "interest", "amount": { "minor_units": 31344, "currency": "MXN" }, "tax": { "minor_units": 5015, "currency": "MXN" }, "total": { "minor_units": 36359, "currency": "MXN" } },
            { "charge": "principal", "amount": { "minor_units": 51291, "currency": "MXN" }, "tax": { "minor_units": 0, "currency": "MXN" }, "total": { "minor_units": 51291, "currency": "MXN" } }
          ]
        }
      ]
    }
  ],
  "anomalies": []
}

The answer is 201, settled is the whole 90066, and excess is zero. Inside Period 1 the money ran fee, then interest, then principal, each charge with its tax beside it. The cut receipt block echoes the report, with the Platform’s id and reported_at added.

Read the payment options

Ask what the Client owes, as of a date you name: the Platform supplies no today, and a read without on is refused 422. The route answers per Loan: what is overdue, the next instalment, the payoff, and what an unnamed amount would do.

Read the payment options

curl "https://api.capcells.com/v1/tenants/$TENANT_ID/clients/c-0001/payment-options?on=2026-04-13" \
  -H "Authorization: Bearer $CAPCELLS_API_KEY"

Response

{
  "client_id": "c-0001",
  "on": "2026-04-13",
  "loans": [
    {
      "loan_id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
      "reference": "loan-0001",
      "overdue": { "total": { "minor_units": 0, "currency": "MXN" }, "charges": [] },
      "instalment": {
        "index": 2,
        "scheduled_on": "2026-05-02",
        "due_on": "2026-05-04",
        "owed": { "total": { "minor_units": 90066, "currency": "MXN" }, "charges": [ … ] },
        "actionable_from": "2026-05-04",
        "requires_overdue_settled": false
      },
      "payoff": {
        "owed": { "total": { "minor_units": 787367, "currency": "MXN" }, "charges": [ … ] },
        "actionable_on": "2026-04-13",
        "requires_payoff_intent": true,
        "requires_designation": false
      },
      "any_other_amount": {
        "treatment": "reduces_principal",
        "description": "everything overdue is settled first; what remains is applied exclusively to outstanding principal under the statutory rule on early payment, which keeps the term and lowers the payments that follow"
      },
      "anomalies": []
    }
  ]
}

The two cut charges arrays split each total by fee, interest and principal, as on the Receipt above. overdue.total is zero, and instalment names Period 2, due 2026-05-04, at the same 90066. payoff.owed.total answers 787367 (MXN 7,873.67) for 2026-04-13: a payoff is stated by payoff_intent on its Receipt, never inferred from the amount.

Getting started

Authentication

Lending

Prerequisites

Issue a Loan

Create the configuration

Register the Client

Preview the Loan

Issue the Loan

Report the money

Report the Receipt

Read the payment options

​Prerequisites

​Issue a Loan

Create the configuration

Register the Client

Preview the Loan

Issue the Loan

​Report the money

Report the Receipt

Read the payment options

Prerequisites

Issue a Loan

Report the money