Integrate

Embed Kept in your platform

The integration pattern for marketplaces, freelance and home-services apps.

This is the pattern for platforms where your users pay each other: freelance marketplaces, home-services apps, B2B ordering, creator commissions. Your platform keeps its own UX; Kept holds the money, enforces the rules and keeps the receipts.

Who calls what

StepWhoCall
Create the promiseYour server, for the user who starts the dealPOST /v1/contracts
Show the proved termsYour UIGET /v1/contracts/{id} (render rendered, verification, nextActions)
Invite the other sideYour app sends the inviteUrlThe invitee accepts on Kept, or you call POST /v1/invites/accept with their key
ApproveEach sidePOST /v1/contracts/{id}/approve with termsHash
FundThe payerPOST /v1/contracts/{id}/fund, then redirect to approveUrl
ConfirmYour return pagePOST /v1/contracts/{id}/fund/confirm
DeliverThe payeePOST /v1/contracts/{id}/uploads then POST /v1/contracts/{id}/evidence
ReviewThe payerPOST /v1/evidence/{id}/accept, reject, challenge; the payee can dispute
TrackYour serverWebhooks for every journal event

Each user acts with their own API key, so Kept's authorization checks hold for every call: a payer can't approve on behalf of a payee, and nobody can read a promise they're not part of.

Rules for a safe integration

  1. Drive every button from nextActions. It is computed on the server for the calling user. If an action isn't there, don't show it.
  2. Trust webhooks, not redirects. A user landing on your ?funding=approved page proves nothing. Call fund/confirm (idempotent) or wait for the signed webhook.
  3. Verify every webhook signature with verifyWebhook from @kept/sdk and reject anything older than five minutes.
  4. Show the terms fingerprint (first 8 characters of termsHash) wherever users approve, and encourage them to compare it.
  5. Keep API keys on your server. Never ship them to a browser or app.
  6. Use the formatted money strings the API returns, and show every number: hold, fee cap, captured, paid out, voided, refunded.
  7. Don't let users edit amounts after approval. Any change creates new terms with a new fingerprint and both approvals reset, by design.

Statuses to design for

StatusShow
draft, compiling, verifyingProgress (GET /compile steps)
needs_attentionThe counterexample and the AI's questions; let users rephrase
reviewPromises, rules, the proof, both approval states, the fingerprint
awaiting_funding, fundingThe hold amount and a PayPal button
activeMoney held / released / returned, deadlines, deliveries
settlingPayPal is executing the final transfers
settledA certificate and the proof pack
frozenThe reason; nothing moves until an arbiter resumes it
cancelledClosed before any money moved

Redirect URLs

PayPal returns the payer to https://kept-rho.vercel.app/contracts/{id}?funding=approved (or cancelled). If your platform hosts the flow, set the deployment's SITE_URL to your own domain and serve those paths. Abandoned checkouts can be reset with POST /v1/contracts/{id}/fund/reset; cancelling is refused while a checkout is open, so a late approval can never strand money.

Sandbox to production

Switch PAYMENT_RAIL from sim to paypal, set the PayPal REST credentials and webhook id, and test with sandbox buyer and seller accounts first. See Fees & money flows for exactly which PayPal calls happen when.

Improve this page on GitHub