API Reference

Base URL: https://fincobra.com

Checkout API

These endpoints are served by the checkout service and handle configuration, invoices, and payments.

Configuration

Method	Path	Auth	Description
GET	/api/checkout/config	Required	Get your checkout configuration
PUT	/api/checkout/config	Required	Create or update configuration
GET	/api/checkout/config/balance	Required	Get wallet balance

Invoices

Method	Path	Auth	Description
POST	/api/checkout/invoices	Required	Create a new invoice
GET	/api/checkout/invoices	Required	List invoices (with filters)
GET	/api/checkout/invoices/stats	Required	Get invoice count by status
GET	/api/checkout/invoices/:id	Required	Get full invoice detail + QR code
GET	/api/checkout/invoices/:id/status	Required	Get invoice status (lightweight)

Payment page

Method	Path	Auth	Description
GET	/api/checkout/pay/:id	None	Public invoice data for payment page

Main API

These endpoints are served by the main FinCobra backend and handle API key management. They require session or bearer token authentication.

API key management

Method	Path	Auth	Description
POST	/api/users/:id/checkout-api-key	Session/Bearer	Generate a new API key (max 3 active)
GET	/api/users/:id/checkout-api-keys	Session/Bearer	List active API keys
DELETE	/api/users/:id/checkout-api-key/:keyId	Session/Bearer	Revoke an API key

Authentication methods

Method	Header/Cookie	Used for
API Key	X-Api-Key: fc_live_...	Programmatic access to checkout API
Session	session cookie (JWT)	Browser-based dashboard access
Bearer	Authorization: Bearer <jwt>	Server-to-server or mobile

Common error format

All errors follow the same shape:

{
  "error": "Human-readable error message"
}

Validation errors may include additional detail:

{
  "error": "Validation failed",
  "details": { ... }
}

HTTP status codes

Code	Meaning
200	Success
201	Created (new invoice)
400	Validation error
401	Authentication failed
404	Resource not found
409	Conflict (duplicate xpub, max keys reached)
502	Upstream service error (wallet balance)

Rate limits

API key management endpoints have strict rate limits. Invoice creation and listing have moderate limits. If you exceed the limit, you'll receive a 429 Too Many Requests response.