API reference

Everything below is rendered from openapi.yaml at build time, not written by hand. If an endpoint changes in the specification, this page changes with it.

Coverage is partial and we would rather say so

The specification currently describes the mandate, charge, refund, webhook and checkout surface. Other route groups the server implements are not in the specification yet: merchant onboarding, the token registry, payout-wallet proof, metrics, and the retail endpoints. They are not on this page, and they get documented as they land in the spec rather than before.

Generated from openapi.yaml, Jorvi API, version 0.1.0.30 operations across 15 groups.

/merchants

Method	Path	Auth	Summary
POST	/v1/merchants	public	Create a merchant account (signup)

/mandates

Method	Path	Auth	Summary
POST	/v1/mandates	secret key	Create a subscription mandate
GET	/v1/mandates/{id}	secret key	Retrieve a mandate
GET	/v1/mandates/{id}/charges	secret key	List a mandate's charges
GET	/v1/mandates/{id}/refunds	secret key	List a mandate's refunds
POST	/v1/mandates/{id}/revoke	secret key	Cancel a subscription (merchant-side; stops future pulls)

/charges

Method	Path	Auth	Summary
POST	/v1/charges/{id}/refund	secret key	Refund a settled charge (full or partial)

/webhook_endpoints

Method	Path	Auth	Summary
GET	/v1/webhook_endpoints	secret key	List webhook endpoints (secrets masked)
POST	/v1/webhook_endpoints	secret key	Register a webhook endpoint

/events

Method	Path	Auth	Summary
GET	/v1/events	secret key	List delivered events (newest first)

/checkout

Method	Path	Auth	Summary
GET	/v1/checkout/mandates/{id}	public	[Browser] Checkout view of a mandate
POST	/v1/checkout/mandates/{id}/instruction	public	[Browser] Get the wallet authorization instruction
POST	/v1/checkout/mandates/{id}/refresh	public	[Browser] Re-check on-chain authorization; activates + settles first charge

/tokens

Method	Path	Auth	Summary
GET	/v1/tokens	secret key	List the tokens this merchant accepts
POST	/v1/tokens	secret key	Accept or decline a curated token

/platform

Method	Path	Auth	Summary
GET	/v1/platform/tokens	secret key	The platform token registry

/token_requests

Method	Path	Auth	Summary
POST	/v1/token_requests	secret key	Ask for a token to be curated

/payment_links

Method	Path	Auth	Summary
GET	/v1/payment_links	secret key	List payment links
POST	/v1/payment_links	secret key	Create a payment link

/products

Method	Path	Auth	Summary
GET	/v1/products	secret key	List products
POST	/v1/products	secret key	Create a product
GET	/v1/products/{id}	secret key	Retrieve a product
PATCH	/v1/products/{id}	secret key	Update a product

/customers

Method	Path	Auth	Summary
GET	/v1/customers	secret key	List subscribers

/metrics

Method	Path	Auth	Summary
GET	/v1/metrics	secret key	Windowed merchant metrics

/payout_wallet

Method	Path	Auth	Summary
POST	/v1/payout_wallet	secret key	Set the payout wallet by signature
GET	/v1/payout_wallet/challenge	secret key	Get a message for the wallet to sign
GET	/v1/payout_wallet/link_tx	secret key	Build an unsigned transaction proving wallet control
POST	/v1/payout_wallet/link	secret key	Set the payout wallet by signed transaction

/wallet

Method	Path	Auth	Summary
GET	/v1/wallet/balance	public	Read a wallet's token balance

Status values

Object	status
Mandate	pending active revoked expired completed
Charge	scheduled processing succeeded retrying abandoned skipped
Refund	pending succeeded failed

Authentication

Requests carry your secret key as a bearer token:

Authorization: Bearer sk_test_...

Keys are prefixed by mode. sk_test_ never touches mainnet. The secret key is a server-side credential and must never reach a browser. The browser gets a client_secret scoped to a single mandate instead.

Errors

Errors are returned in a structured envelope, never as a bare string:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Human-readable explanation.",
    "param": "mint"
  }
}

param is present only when the problem is attributable to one field.

Codes

These are the codes verified against the server source. This list is not exhaustive. The specification has no error schema yet, so treat error.code as the value to branch on, and expect codes that are not listed here.

HTTP	type	code	Meaning
400	invalid_request_error	parameter_missing	A required field was absent. param names it.
400	invalid_request_error	parameter_invalid	A field was present but unusable. param names it.
400	invalid_request_error	mint_not_allowed	The token is not on the platform registry.
400	invalid_request_error	mint_not_enabled	The token is allowed platform-wide but not enabled for your account.

Branch on error.code, never on error.message. Messages are written for humans and will change.

Idempotency

Mandate creation and refunds accept an idempotency key so a retried request cannot double-charge or double-refund:

await jorvi.mandates.create(input, { idempotencyKey: 'order-1234' });
await jorvi.charges.refund(chargeId, { idempotencyKey: 'refund-1234' });

Use a key derived from your own order identifier, not a random value, or a retry after a network timeout will create a second object.

Related

• Supported tokens: how a mint becomes usable
• Sandbox: test mode and the local validator