Integration options

Three ways to take a payment. They are not tiers: the hosted page is not a lesser version of the API, it is the same settlement with less of your code in the path.

1. The hosted page, no code

Every product you create comes with a checkout page. Create the product, join its url to your server address, and share the link.

POST /v1/products   ->   { "id": "prod_…", "url": "/product/prod_…" }
                          share $JORVI_API + url

The page handles wallet detection, the approval prompt, the on-chain confirmation, and unlocking what was bought. You write nothing.

Choose this if you are selling a file, a document, access to something, or you want to be taking money today. It is the only option with nothing to maintain when a wallet ships a breaking change.

The trade is that the page is ours. It carries your product name and price, not your design.

2. Your own checkout, plain HTTP

Drive the same flow yourself. Four requests, no dependencies, no SDK:

1. POST /v1/products/:id/buy → a mandateId, a clientSecret, and instruction, which is a complete unsigned transaction in base64
2. The payer signs it in their wallet. In a browser that is their extension
3. POST /v1/checkout/mandates/:id/broadcast → the signature the chain returned
4. GET /v1/products/:id/access → what they bought

Walked through step by step in Accept a payment.

Choose this if the checkout must look like your product, or you are integrating from a language, a bot, or an agent rather than a browser.

The trade is that connecting a wallet and presenting a signing prompt is now yours to build and to keep working.

What you never have to build

Neither option asks you to hold a key, custody funds, or handle a refund path for money you touched on the way through. The payer signs; the tokens move from their wallet to yours. There is no in-between account, because there is nowhere for one to be.

3. The SDK, not yet

@jorvi/sdk and @jorvi/checkout exist in the repository and are not published to npm. Until they are, an npm install will not find them, and this page will not pretend otherwise.

Use option 1 or 2. Both are stable HTTP that a published SDK would call anyway.

Which to start with

Start with the hosted page, even if you intend to build your own. It proves the account, the payout wallet and the token are all configured correctly before any of your code is involved, so when you do move to option 2 you are debugging one thing rather than four.

What to know either way

• Prices are strings in atomic units. USDC has six decimals, so "3000000" is 3.00.
• Getting told about a payment is Webhooks. Do not poll.
• Every failure is a typed code, listed in Errors. Branch on the code, never on the message.
• Subscriptions are not available yet. A deployment that cannot drive renewals refuses to create them rather than accepting an authorization for billing that will never run.