Quickstart

Six calls take an empty sandbox to a loan on record with its first payment settled. It all runs in one shell, and takes a few minutes. Nothing here is real money. A sandbox owes nobody, its records stand for nothing, and every call is safe to repeat.

Before you start

You need two things, and the walk creates everything else.

You need	How to get it
A sandbox tenancy	Registered for you when you sign up. Its records stand for nothing.
A key with write scope	Minted by an administrator at the Console.

Then set two shell variables and paste in the signer, which is the reference implementation on API keys.

Set up the shell

export TENANT_ID="t-0001"
export CAPCELLS_API_KEY="…"

Every request is signed, and nothing secret travels. What goes on the wire is a signature over the request, and the Platform checks it against the public half it holds.

Issue a loan

Four calls turn terms into an agreement on record.

Create the product

Set the terms you sell. The archetype decides which settings the product carries, and any setting it does not carry is refused by name rather than ignored. You do not name the product: the Platform composes its identifier and answers it.

Create the product

BODY='{
    "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" }
    }
  }'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/product-configurations" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/product-configurations" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Response

{
  "id": "inst-000001",
  "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 inst-000001 — the identifier the Platform composed, and the value an issuance names as its configuration_id. Sending the same body again creates a second product, inst-000002; send an Idempotency-Key if you mean one.

Register the borrower

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.

BODY='{ "id": "c-0001", "label": "contract-0001" }'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/clients" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/clients" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

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 names this identifier as its client_id.

Quote the loan

Price the agreement before recording it. A preview takes the same body an issuance takes, without a reference, and records nothing.The loan is MXN 8,000.00 over 12 monthly payments at 45.5% a year, starting 2026-03-02 in Mexico, under the product above. Its penalty rate is 60%, and tax runs at 16% on interest, fee, penalty and late fee.

Quote the loan

BODY='{
    "client_id": "c-0001",
    "configuration_id": "inst-000001",
    "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"] }
  }'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/preview" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/loans/preview" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Response

{
  "configuration": { "id": "inst-000001", "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", "convention": "mx-cat", "convention_version": 1, "provisional": true },
  "regime": {
    "penalty_rate": "60",
    "late_fee": { "minor_units": 15000, "currency": "MXN" },
    "tolerance_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 payment’s 90078 absorbs the 12-centavo residual.

Issue the loan

Send the same body again, now carrying a reference: your own identifier for this agreement, unique in your tenancy. It is what makes a retry safe.

Issue the loan

BODY='{
    "reference": "loan-0001",
    "client_id": "c-0001",
    "configuration_id": "inst-000001",
    "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"] }
  }'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/loans" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

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; the Platform holds the record. Money is reported against the borrower, and every figure after it is derived from that report.

Report the payment

Report the first payment as it arrives. It was scheduled for 2026-04-02, a non-working day in Mexico, so collection moved to 2026-04-06, and that is the date the borrower paid on.

Report the payment

BODY='{
    "reference": "receipt-0001",
    "client_id": "c-0001",
    "amount": { "minor_units": 90066, "currency": "MXN" },
    "value_date": "2026-04-06"
  }'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/receipts" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/receipts" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

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" },
  "absorbed": { "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 the first payment the money ran fee, then interest, then principal, each charge with its tax beside it.

Ask what is owed

Ask what the borrower owes on a date you name. The Platform has no today of its own, so a read without a date is refused. The answer covers each loan: what is overdue, the next payment, the payoff figure, 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: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/$TENANT_ID/clients/c-0001/payment-options?on=2026-04-13")"

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,
        "settled_by": "instalment"
      },
      "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 payment above. overdue.total is zero, no late appears because nothing is behind, and instalment names the second payment, due 2026-05-04, at the same 90066 — settled by its own figure, since its due date has not arrived. payoff.owed.total answers 787367 (MXN 7,873.67) for 2026-04-13: a payoff is stated by payoff_intent on the payment, never inferred from the amount.Reading the options records nothing. When you relay that payoff to the borrower as the figure to pay, record it: the Platform keeps the same figure and the versions that computed it, readable on the loan’s payoff quotes. The record binds nothing: a payment is settled against the figure derived on the day it arrives, never against a figure recorded there.

What you have now

A product on file, a borrower registered against it, a loan of MXN 8,000.00 over twelve payments, and the first of those payments settled. The loan reads active, and the Platform derives what it owes on any date you ask for.

Products

Every setting a product carries, and which archetype to sell under.

Loans

What issuance checks, what it freezes, and the acts that change a loan’s life.

Payments

The order money settles in, and what a borrower may choose to do with it.

Going live

What separates the sandbox from the book that owes real people money.

Getting started

Authentication

Lending

Risk

Markets

Before you start

Issue a loan

Create the product

Register the borrower

Quote the loan

Issue the loan

Report the money

Report the payment

Ask what is owed

What you have now

Products

Loans

Payments

Going live

​Before you start

​Issue a loan

Create the product

Register the borrower

Quote the loan

Issue the loan

​Report the money

Report the payment

Ask what is owed

​What you have now

Products

Loans

Payments

Going live

Before you start

Issue a loan

Report the money

What you have now