Payment APIs taught a generation of developers what good infrastructure feels like. Insurance can borrow most of that playbook — but three properties of insurance break the analogy, and the API design has to absorb them.
Ask a developer what a good API feels like and they will describe a payments API: one clean object model, a sandbox that behaves like production, webhooks that tell the truth, and errors that explain themselves. When we designed Yasmina's platform we started from that canon deliberately. Most of it transferred. Three things did not, and they are the interesting part.
What transferred straight across
Idempotency everywhere. A policy purchase, like a charge, must be safe to retry. Every mutating call accepts an idempotency key; a network timeout can never mean "did the customer just buy two policies?" This is table stakes in payments and still novel in insurance integrations, where retry-induced duplicate policies remain a real industry failure mode.
Sandbox parity. Our sandbox returns the same payload shapes production returns — same policy numbers format, same certificate URLs, same commission lines — because the lesson from payments is that partners ship against what the sandbox teaches them. A sandbox that lies is a production incident on a delay timer.
Webhooks as the source of motion. Policy issued, document ready, payout computed: push, don't make partners poll. And because delivery is at-least-once, every event is re-fetchable by ID — the webhook is a doorbell, not the package.
Errors written for the integrating developer. "Vehicle year must be 2005 or later for comprehensive plans" beats "VALIDATION_ERROR." Every error names the field, the rule and, where safe, the fix.
Where insurance broke the analogy
A charge has one price; a risk has a quote. Payments APIs answer "move this amount." Insurance APIs must first answer "what would cover this risk cost?" — and that answer varies by underwriter, expires, and depends on data quality. So quoting is a first-class resource in our model, not a parameter on purchase: quotes have IDs, lifetimes, and a guarantee that the quoted price is the charged price for the quote's lifetime. Most integration pain we see elsewhere traces to APIs that treat the quote as a throwaway calculation instead of a contract.
The document is the product. Nobody frames a receipt. An insurance certificate, by contrast, is a legal artefact someone will present at a traffic stop or a visa counter. That forces design decisions payments never faces: documents are issued synchronously with the policy (a policy without its certificate is not "done"), URLs are stable and permission-controlled, and regeneration is versioned because regulators care which wording the customer received.
Policies live for a year; charges live for a second. A charge's lifecycle is created→settled→maybe-refunded, measured in moments. A policy will be endorsed, cancelled mid-term with pro-rata maths, renewed, claimed against. Modelling that meant learning from subscription APIs more than charge APIs — explicit state machines, effective-dated changes, and events for every transition, because the platform that sold the policy needs to reflect its state for the whole year it exists.
The test we hold ourselves to
The 24-hour integration is our forcing function: if a partner's engineers cannot go from sandbox key to issued test policy inside a day, the API — not the partner — has failed. The payments industry proved that infrastructure adoption is won by the developer experience, one integration at a time. Insurance is later to that lesson only because its complexity gave it an excuse. The complexity is real; the excuse is not — the job is to absorb it behind the API, so the partner's checkout only ever sees the simple part.