Developer›API reference

API reference.

The OpenSettle API is organized around REST. It uses resource-oriented URLs, accepts JSON request bodies, and returns JSON. The current version is v1.

Interactive reference

Try-it-out three-pane explorer rendered from the live OpenAPI 3.1 spec. Schemas, examples, and response shapes for every public route.

Open reference →

Base URL

bash

https://api.opensettle.io

OpenAPI spec: api.opensettle.io/v1/openapi.json — consume it with Scalar, Stoplight, or any OpenAPI-aware tool.

Authentication

Authenticate with a workspace-scoped API key as a Authorization: Bearer header. Keys come in two scopes: sk_live_… and sk_test_…. Test-mode keys behave identically against the same hostname; there is no separate test API origin.

bash

curl https://api.opensettle.io/v1/workspaces/ws_.../payments \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxa2E1"

Every merchant route is workspace-scoped under /v1/workspaces/:workspaceId/…. All POST mutations require an Idempotency-Key header.

Resources

Checkouts

Hosted or embedded one-time payments.

Open ref →

POST/v1/workspaces/:workspaceId/checkouts
GET/v1/workspaces/:workspaceId/checkouts/:id

Subscriptions

Recurring billing with invoice, dunning cascade, and self-service cancellation.

Open ref →

POST/v1/workspaces/:workspaceId/subscriptions
GET/v1/workspaces/:workspaceId/subscriptions/:id
POST/v1/workspaces/:workspaceId/subscriptions/:id/cancel
POST/v1/workspaces/:workspaceId/subscriptions/:id/pause
POST/v1/workspaces/:workspaceId/subscriptions/:id/resume
POST/v1/workspaces/:workspaceId/subscriptions/:id/change_plan

Payments

Confirmed and pending on-chain settlements.

Open ref →

GET/v1/workspaces/:workspaceId/payments
GET/v1/workspaces/:workspaceId/payments/:id
POST/v1/workspaces/:workspaceId/payments/:id/refund

Customers

Your customer records and their wallets.

Open ref →

POST/v1/workspaces/:workspaceId/customers
GET/v1/workspaces/:workspaceId/customers/:id
PATCH/v1/workspaces/:workspaceId/customers/:id
DELETE/v1/workspaces/:workspaceId/customers/:id

Invoices

Generated automatically or created ad-hoc. CSV export carries customer + on-chain settlement fields.

Open ref →

GET/v1/workspaces/:workspaceId/invoices
GET/v1/workspaces/:workspaceId/invoices?format=csv[&from=…&to=…]
POST/v1/workspaces/:workspaceId/invoices
GET/v1/workspaces/:workspaceId/invoices/:id
POST/v1/workspaces/:workspaceId/invoices/:id/send
POST/v1/workspaces/:workspaceId/invoices/:id/reminder
POST/v1/workspaces/:workspaceId/invoices/:id/void

Webhook endpoints

Where OpenSettle sends signed event notifications.

Open ref →

POST/v1/workspaces/:workspaceId/webhook_endpoints
GET/v1/workspaces/:workspaceId/webhook_endpoints
POST/v1/workspaces/:workspaceId/webhook_endpoints/:id/rotate
POST/v1/workspaces/:workspaceId/webhook_endpoints/:id/test
GET/v1/workspaces/:workspaceId/webhook_endpoints/:id/deliveries
POST/v1/workspaces/:workspaceId/webhook_endpoints/:id/deliveries/:deliveryId/replay

Workspaces

Workspace management + the customer-facing public profile slug for /u/<slug>.

Open ref →

GET/v1/workspaces
POST/v1/workspaces
GET/v1/workspaces/:workspaceId
PATCH/v1/workspaces/:workspaceId
PUT/v1/workspaces/:workspaceId/public-slug
DELETE/v1/workspaces/:workspaceId/public-slug

Public (no auth)

Hosted-page hydration endpoints + the public profile permalink. Rate-limited per IP.

Open ref →

GET/v1/i/:token
GET/v1/checkout/:id
POST/v1/checkout/:id/prepare-payment
POST/v1/checkout/:id/attestation
GET/v1/u/:slug
POST/v1/u/:slug/contact
GET/v1/img/logo/:workspaceId

Errors

Errors use standard HTTP status codes. Our body is a typed shape with a machine-readable code, a human-readable message, and — when applicable — a request ID for support.

error

{
  "error": {
    "code": "invalid_request",
    "message": "Either customerId or customerEmail is required",
    "param": "customerId",
    "request_id": "req_01HGKM4Z7WQ4X"
  }
}

On GitHub