inst-000001, bnpl-000001, payd-000001. Every one is the same eleven characters, so a catalogue reads down one column. You do not choose it and cannot. It is what every loan records, what a support thread names, and what your catalogue reads as. What your code holds instead is a lookup key of your own. The Platform holds no name for a product either — what the borrower sees on the contract and the statement is yours to print.
Create a product
Set the terms of the offer: the shape it repays in, the amounts, the rates, the fees.
Register a borrower
Register each borrower you lend to under your own identifier. See Clients.
Issue a loan
Issue a loan naming the product and the borrower, and pick one point inside every range. See Loans.
Archetypes
Every product is built on an archetype: the shape in which the borrower repays. There are three, and the archetype is chosen when the product is created and never changes afterwards. A different repayment shape means a different product. The archetype also decides which terms the product can carry at all. A Pay Day Loan has no menu of instalments, and an Instalment product has no rollover fee. Choose by how the money comes back, not by how much it is. An amount repaid in one go is a Pay Day Loan whether it is 500 or 15,000.Instalment
The borrower repays over several equal payments, usually monthly. You offer a menu of terms, such as six, twelve or eighteen months, and each loan is issued for one of them. Use it for cash lending: personal loans, payroll-deducted loans, consumer credit repaid over months. It is the shape most consumer credit takes, and the one most borrowers expect. A borrower taking 8,000 for a fridge over twelve months pays about 900 a month, in whatever currency the product is priced in. What is particular to it. You offer a menu of terms and each loan is issued for one of them; a term outside the menu is refused rather than rounded to the nearest one. The payment is worked out for you so that the loan is level: every payment is the same, and the share of it that is principal grows as the balance falls. You can set a floor under the payment, below which you will not sell. A loan that comes out under the floor is refused, not stretched over a longer term to clear it.
Returns. An instalment product sold at a checkout, a counter or a bill desk finances a purchase, and a return is admitted on its loans exactly as on a Buy Now Pay Later one. Nothing is set on the product: the return is your statement that goods went back.
Buy Now Pay Later
The borrower splits a purchase into a few payments and pays the first one at the till. The rest fall due on a short cycle, typically every fortnight. Use it when you finance a purchase at the point of sale rather than lending cash. The purchase amount, not the borrower’s request, sets the principal, and the store is usually part of the commercial arrangement. A borrower buying 2,000 of clothes pays 500 at the till, then 500 every fortnight three times more. What is particular to it. The payment at the till is part of the shape, not an option: every loan states it, and issuing the loan settles it. You can also record what the arrangement with the store is worth, as a commission in basis points. It runs both ways: positive when the store pays you for financing the sale, negative when you pay the store for bringing you the customer. The Platform stores the number and reports it back, and settles nothing with the store on your behalf.
Returns. When goods go back you record a return: the principal falls by what they were worth and the payments are lowered, with the term kept.
Pay Day Loan
The borrower repays everything on one date, typically their next pay day. There are no instalments: one advance, one repayment, and the cadence you set decides how far out that date falls. Use it for short advances against income. It is the only shape in which a borrower can roll the loan over, paying the cost accrued so far and carrying the balance to a later date. A borrower taking 3,000 ten days before pay day repays the 3,000 and the interest in one payment on pay day. What is particular to it. There is no menu of terms. The cadence you set on the product decides how far out the single date falls: a fortnightly cadence makes a loan due a fortnight after it is issued. It is also the only shape that can be rolled over. The product decides two things about that: what one rollover costs on top of the interest accrued, and how many a single loan may carry. A product that names no rollover cost does not allow the operation at all, and a limit of zero forbids it. How a rollover is recorded, and what it collects, is on Loans.
A Pay Day Loan admits no return: a single-period advance finances nothing anybody sends back, and recording one is refused as
return_not_provided.
If you sell the same offer in two repayment shapes, that is two products. There is no way to convert one into the other later.
What a product sets
A product carries seven decisions, under an identifier the Platform composes. Each one applies to every loan issued under it, and each loan picks a point inside whatever range you set.The amounts
A smallest and a largest. Every loan falls between them, and one that does not is refused rather than trimmed to fit.A product is priced in one currency, and that cannot be changed later, not even by a new version. To sell the same offer in another currency, create a second product.
The price
A range of interest rates rather than a single rate, so each loan can be priced for the borrower in front of you. Rates are stated per year, and each loan names one rate inside the range. You also choose how a year is counted, and there are three conventions.The schedule
How often payments fall due. Fortnightly and twice-monthly cadences are common wherever borrowers are paid that way.
A product may admit more than one schedule, at most one of each kind, and let each loan choose. A fortnightly product that admits
anchored_every_n_days at 14 days and the semi_monthly_grid on the 15th and the last day lets the borrower pick “every two weeks from today” or “on pay days”; a monthly product that admits anchored_monthly and monthly_on_day lets them pick the purchase’s day or a day of their own. The issuance names the choice; a product admitting one schedule needs no choice at all.
A payment landing on a weekend or a public holiday is collected on the next banking day of the borrower’s market. The date the borrower must pay by moves; the amount does not.
You can also require a minimum gap between the day a loan starts and its first payment, so that a loan issued two days before pay day does not fall due immediately.
The fees
Two, and both optional. A fee you do not set is a fee your borrowers never pay. A fee charged when the loan is issued is spread evenly across the payments rather than taken as a lump at the start, and it never accrues interest. A flat late fee is charged once, when a payment goes past its tolerance days.Late payment
Every product states a range of penalty rates, and this one setting is required. A product that cannot say what happens when it is not paid is not a complete offer, and a rate invented at the moment of default is a term nobody agreed to. A product that charges no penalty says so, as a range of zero. Around it are four optional settings, and the Platform sets none of them for you.
Tolerance days are días de tolerancia, not a período de gracia. A período de gracia is an initial stretch of the loan in which no principal falls due, which is a different product feature and not this setting.
Delinquency covers when a payment becomes overdue and how these charges accrue.
Early payment
When money arrives beyond what is due, it does one of two things, and you decide which.
Where a market fixes the answer, that answer is the default: in Mexico, reducing the balance is what the law requires unless the borrower asks otherwise. Markets lists what each market fixes, and Payments covers what a borrower may choose on the money itself.
Credit lines
Settingrequires_facility makes every loan of the product draw against a grant made to the borrower in advance, rather than be issued one at a time. Use it where the decision to lend is made once and drawn down over time — and grant a line where repayments should free capacity again. Facilities covers what a grant fixes and what a draw is held against.
Three optional fields hold every issuance to the client’s whole book: max_open_loans_per_client, max_outstanding_per_client and refuse_while_any_loan_overdue. They are read at issuance, over every loan of the client’s whatever product it was issued under; Client guards says how.
Set all of these when you create a product, and change them by publishing a new version. The API reference carries the exact format, the limits and the error each one returns.
The identifier
You set nothing here. When you create a product the Platform answers an identifier built to one rule: a four-letter code for the archetype, a hyphen, and a six-digit number counted within your tenancy and within that archetype. Your first instalment product isinst-000001, your second inst-000002, and your first pay-day product is payd-000001 however many instalment products came before it. The codes are inst, bnpl and payd, and every identifier is eleven characters.
Unlike the terms, the identifier is not part of the version: it is fixed when the product is created and never changes, because it is what every loan issued under it names. Another lender’s catalogue starts at inst-000001 too; the identifier names a product within your tenancy and nowhere else.
Because you name nothing, two creates of the same body are two products. Send an idempotency key if you mean one — a form submitted twice is what it is for. You can also preview a product before creating it and see the identifier it would take.
Try before you create
A product cannot be deleted, so a mistaken one stays in your catalogue. Before you create one, try the body: the same body, the same checks, and nothing written. If the Platform would refuse it, you see the refusal now, naming the field. If it would accept it, you see the terms as they will read back. A new version has the same preview. What each archetype admits — which fields, which are required, which it locks, and every limit — is read from the Platform rather than copied from this page, so a form built on it cannot fall behind.Changing your terms
A product is never edited. When your terms change, you publish a new version of it, and version numbers count up from one. Loans already issued are not affected: each keeps the version it was issued under for its whole life, along with its schedule, its payments and the cost figure you disclosed. Raising your rates next quarter does not reach a loan sold this quarter, and that is the point. Every version stays readable for as long as a loan names it. A loan always names a version by number. A new version sells nothing on its own: it goes on sale when you move a lookup key to it. Two things cannot be changed by a version, because they change what the product is rather than what it costs: the repayment shape and the currency. Each needs a new product. A lender selling a personal loan in two currencies and a payday advance therefore runs three products.Selling under a lookup key
The identifier differs between environments — your sandbox and your live Tenancy are two catalogues, and the same product can beinst-000002 in one and inst-000003 in the other. The version you sell changes every time your terms do. Neither belongs in your code or your environment variables.
A lookup key is a word of your own for a product you sell — meses, quincenas — pointed at one version of one product. Your code holds the key, the same in every environment. The Platform answers which product and version it names.
Point a key once per environment
Point
meses at inst-000003 version 3. The key names that version and no other.Resolve your keys when a page is priced
One read with
?lookup_key=meses&lookup_key=quincenas answers every product on the page, with each version’s terms. Read when you price, not once at start-up: a copy kept from start-up misses the next move.Sell under the pair the read answered
Every selling request — a preview, a decision, an issuance — still names
configuration_id and configuration_version. Fill them from the read. No request takes a key.transfer: true. Without transfer, a key that names another version is refused lookup_key_taken, naming where it points — so a key you believed was new cannot silently replace a product on sale. The product keeps its identifier; only the key moves. Every pointing is recorded, so what a key sold on any past day is on record.
On a live Tenancy only a person or your own key can point or remove a key. An agent may read keys, and on a sandbox it may point them.
FAQ
Can one product be sold in two countries?
Can one product be sold in two countries?
Yes. A product names no country. The loan does, and that is what decides the holiday calendar, the legal ceiling on the penalty rate and the disclosed cost figure. What a product cannot span is two currencies.
Can I change a product's archetype later?
Can I change a product's archetype later?
No. The repayment shape is fixed when the product is created, and no version changes it. Create a second product and issue new loans under that one.
How do I raise my rates without touching loans already sold?
How do I raise my rates without touching loans already sold?
Publish a new version with the new range. Loans issued under earlier versions keep them for life, so there is nothing to protect them from.
Why must every product state a penalty rate?
Why must every product state a penalty rate?
Because a product that cannot say what happens when a borrower does not pay is not a complete offer, and a penalty rate invented at the moment of default is a term nobody agreed to. A product that charges no penalty states that, as a range of zero.
Do my sandbox and live code need different product identifiers?
Do my sandbox and live code need different product identifiers?
No. Point the same lookup keys in each environment and let your code hold only the keys. Each environment answers its own identifier and version.
How many products should we have?
How many products should we have?
As few as your price list has offers. Most lenders run between two and six. If two rows on your price list differ only in rate, they are one product with different loans; if they differ in how the money comes back, they are two products.